> 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

You need:

* Auction Plus installed in Shopify
* Access to **Settings** → **API**
* 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
```

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           |

## Common endpoints

Start with these auction item endpoints:

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

See [Auction Items](broken://spaces/sQVmXQ0YPLAOjdunzCT9/pages/6348f96fce73c7df47bf23384fdcbb05cd3fef80) 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](broken://spaces/sQVmXQ0YPLAOjdunzCT9/pages/bd0b854072afcdb55143d855a6d6aab9fcdfccc9) 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