> For the complete documentation index, see [llms.txt](https://docs.auctionplusapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auctionplusapp.com/admin-api/getting-started.md).

# Getting Started

Use this guide to send your first authenticated request to the Auction Plus REST API. It covers authentication, request structure, response structure, and the basics of rate limiting.

## Before you start

Before using the Admin API, ensure your shop has:

* Auction Plus installed in Shopify.
* A plan that supports API access.
* A secure server-side environment for your token

## Base URL

Send all requests to:

```
https://api.auctionplusapp.com/v1
```

## Authentication

The API uses bearer token authentication.

### Generate an API token

1. Open Auction Plus in Shopify.
2. Go to **Settings**.
3. Open **API**.
4. Click **Generate Private Token**.

Store the token securely. It is only shown once.

### Send the token in the `Authorization` header

Include these headers with every request:

```http
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json,application/vnd.api+json
```

If the token is missing or invalid, the API returns `401 Unauthorized`.

## Make your first request

Use the auction items endpoint to test your connection.

{% code title="cURL" %}

```bash
curl --request GET \
  --url https://api.auctionplusapp.com/v1/auction-items \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Accept: application/json"
```

{% endcode %}

A successful request returns a `data` object or array. List endpoints may also return pagination details in `meta`.

## Response format

Most endpoints return a resource-based JSON payload:

```json
{
    "data": [
        {
            "id": "34dhchwby12yzfhgk6d6t86e3c",
            "type": "auction-items",
            "attributes": {
                "status": "active",
                "totalBids": 12
            }
        }
    ],
    "meta": {
        "currentPage": 1,
        "lastPage": 1,
        "perPage": 25,
        "total": 1
    }
}
```

### Common response fields

| Field        | Description                       |
| ------------ | --------------------------------- |
| `data`       | Primary resource or resource list |
| `id`         | Resource identifier               |
| `type`       | Resource type                     |
| `attributes` | Resource fields                   |
| `meta`       | Pagination or response metadata   |

## Common request patterns

The API follows standard REST conventions:

* `GET` retrieves resources
* `POST` creates resources when supported
* `PATCH` updates resources or triggers actions

Many endpoints also support filtering, sorting, sparse fieldsets, and related resources.

### Common query parameters

| Parameter               | Description                          |
| ----------------------- | ------------------------------------ |
| `include`               | Include related resources            |
| `sort`                  | Sort by a supported field            |
| `perPage`               | Set the page size for list endpoints |
| `fields[resource-type]` | Return only selected fields          |
| `filter[...]`           | Filter supported endpoints           |

### Deleted customers

In some cases, a resource may be deleted or redacted. For resources that include redacted relationships, a subset of its information is returned, including a `deleted` attribute set to `true`:

```json
{
    "id": "34dhchwby12yzfhgk6d6t86e3c",
    "type": "customers",
    "attributes": {
        "deleted": true
    }
}
```

## Common endpoints

Start with these auction item endpoints:

* `GET /auction-items` — List auction items
* `GET /auction-items/{id}` — Retrieve one auction item
* `POST /auction-items/{id}/end` — End a listing early
* `POST /auction-items/{id}/cancel` — Cancel a listing without assigning a winner

See [Auction Items](https://github.com/treoapps/docs/tree/main/admin-api/auction-items/README.md) for full request and response schemas.

## Error handling

Use the HTTP status code first. Then inspect the response body.

| Status code                | Meaning                                                     |
| -------------------------- | ----------------------------------------------------------- |
| `200 OK`                   | Request succeeded                                           |
| `401 Unauthorized`         | Token is missing, expired, or invalid                       |
| `404 Not Found`            | The resource does not exist                                 |
| `422 Unprocessable Entity` | The request body is valid JSON but invalid for the endpoint |
| `429 Too Many Requests`    | Rate limit exceeded                                         |

## Rate limits

The API applies request limits to each authenticated user.

If you exceed the limit, the API returns `429 Too Many Requests`.

See [Rate Limiting](/admin-api/rate-limiting.md) for bucket values, response headers, and retry guidance.

## Best practices

* Keep API tokens in trusted server-side environments
* Paginate large result sets
* Request only the fields and includes you need