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 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:

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. A customer 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.

cURL

curl --request GET \
  --url https://api.auctionplusapp.com/storefront/v1/auction-items \
  --header "Authorization: Bearer STOREFRONT_TOKEN" \
  --header "Accept: application/vnd.api+json"

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:

{
    "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

Per-viewer fields

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

cURL

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"

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

{
    "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

• 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, Variants, and Watched Items 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:

{
    "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 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