> 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/storefront-api/getting-started.md).

# Getting started

Authenticate and make your first request to the Auction Plus Storefront API.

Use this guide to send your first authenticated request to the Auction Plus Storefront API. It covers authentication, identifying the customer, request structure, response structure, per-viewer fields, and the basics of rate limiting.

The Storefront API powers customer-facing auction experiences such as listing and searching auction items, placing bids, and managing watched items. For server-side automation and merchant tooling, use the [Admin API](/admin-api/getting-started.md) instead.

## Before you start

Before using the Storefront API, ensure your shop has:

* Auction Plus installed in Shopify.
* A plan that supports API access.

## Base URL

Send all requests to:

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

## Authentication

The Storefront API uses bearer token authentication with a public token.

### Generate a storefront token

1. Open Auction Plus in Shopify.
2. Navigate to **Settings** → **API**.
3. Under the **Storefront API** section, select **Generate Public Token**.

Storefront tokens are for client-side use. Select **Full** access to place bids or manage watched items. Select **Read only** to retrieve auction data only.

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

Include these headers with every request:

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

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

## Identifying the customer

Requests are anonymous by default. To make requests for a signed-in customer, include their Shopify Customer Account API access token in the `X-Shopify-Customer-Access-Token` header.

Invalid or expired tokens return `401 Unauthorized`. An active customer account is required to place bids, manage watched items, or use `filter[viewerHasBid]` on auction items.

## 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/storefront/v1/auction-items \
  --header "Authorization: Bearer STOREFRONT_TOKEN" \
  --header "Accept: application/vnd.api+json"
```

{% endcode %}

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

## Response format

Endpoints return a resource-based JSON payload:

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

### Common response fields

| Field        | Description                                   |
| ------------ | --------------------------------------------- |
| `data`       | Primary resource or resource list             |
| `id`         | Resource identifier                           |
| `type`       | Resource type                                 |
| `attributes` | Resource fields                               |
| `included`   | Related resources requested with `include`    |
| `meta`       | Pagination, per-viewer, and response metadata |

## Common request patterns

The API follows standard REST conventions:

* `GET` retrieves resources.
* `POST` places bids and watches variants.
* `DELETE` removes a watched variant.

List endpoints 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                   |
| `viewerFields`          | Return per-viewer fields under `meta.viewer` |

### 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
    }
}
```

## Per-viewer fields

Fields that depend on the authenticated customer are opt-in. Request them by name using the viewerFields query parameter:

{% code title="cURL" %}

```bash
curl --request GET \
  --url "https://api.auctionplusapp.com/storefront/v1/auction-items?viewerFields=hasBid,isWatching" \
  --header "Authorization: Bearer STOREFRONT_TOKEN" \
  --header "X-Shopify-Customer-Access-Token: CUSTOMER_ACCESS_TOKEN" \
  --header "Accept: application/vnd.api+json"
```

{% endcode %}

Requested fields are returned under `meta.viewer` on the resource and on any included resources that support them:

```json
{
    "data": {
        "id": "34dhchwby12yzfhgk6d6t86e3c",
        "type": "auction-items",
        "attributes": { "status": "active" },
        "meta": {
            "viewer": {
                "hasBid": true,
                "isWatching": false
            }
        }
    }
}
```

| Resource        | Field          | Description                               |
| --------------- | -------------- | ----------------------------------------- |
| `auction-items` | `hasBid`       | The customer has placed a bid on the item |
| `auction-items` | `isWatching`   | The customer is watching the item         |
| `auction-items` | `isHighBidder` | The customer holds the current high bid   |
| `bids`          | `isOwner`      | The bid belongs to the customer           |

Unknown field names are ignored. When no customer is identified, `meta.viewer` is omitted entirely.

## Common endpoints

Use these endpoints to browse auctions, place bids, and manage watched items:

* `GET /auction-items` — List auction items
* `GET /auction-items/search` — Search auction items by product title
* `GET /auction-items/{id}` — Retrieve one auction item
* `POST /auction-items/{id}/place-bid` — Place a straight or max bid
* `PATCH /auction-items/{id}/max-bid` — Update the customer's max bid
* `GET /variants` — Look up variants by Shopify variant ID
* `GET /watched-items` — List the customer's watched variants
* `POST /watched-items` — Watch a variant
* `DELETE /watched-items` — Unwatch a variant

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

## Error handling

Errors are returned in JSON:API format. Inspect `errors[0].code` for the specific reason. Bid failures, for example, report codes such as `auction_ended` or `amount_below_showing_bid`, with the minimum acceptable value in `meta.minimum_bid`:

```json
{
    "errors": [
        {
            "status": "422",
            "code": "amount_below_showing_bid",
            "detail": "The amount must be greater than the leading bid plus the bid increment.",
            "meta": { "minimum_bid": "55.00" }
        }
    ]
}
```

## Rate limits

All Storefront API requests are rate limited based on the the **buyer's IP address**.

See [Rate Limiting](/storefront-api/rate-limiting.md) in the API reference for how limits are applied.

## Best practices

* Request `viewerFields` only when a customer is identified
* Request only the fields and includes you need.
* Cache frequently used data.
* Paginate large result sets.
* Revoke tokens from **Settings** → **API** if they are no longer used