Rate limits, pagination & versions

Request limits, paging through results, and API version headers.

​

Rate limits

Limit	Applies to	Allowance
Per store	All requests with the same shop and API key	600 requests per minute
Failed keys	Requests from one IP with a wrong key	20 per minute, then that IP is blocked for the rest of the minute
Per guest	Requests from one guest session	60 per minute
Share by email	One shopper sending share emails	60 per minute

Over a limit, the API returns 429 RATE_LIMITED. The per-store and failed-key limits include a Retry-After header (seconds). For the per-guest and share limits, wait a few seconds before retrying.

async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
    await new Promise(r => setTimeout(r, wait * 1000));
    return call(url, init, attempt + 1);
  }
  return res;
}

​

Pagination

List endpoints use page numbers.

Query parameter	Default	Allowed
page	1	Whole number ≥ 1
limit	5	1–50

Paged responses include:

"pagination": {
  "page": 1,
  "limit": 8,
  "totalItems": 13,
  "totalPages": 2,
  "hasNextPage": true,
  "hasPrevPage": false
}

Keep loading while hasNextPage is true. To match the storefront, use the merchant’s page sizes from GET /settings: widgetSettings.wishlistPerPage for lists and widgetSettings.wishlistDetailItemsPerPage for items.

GET /wishlists pages the lists, and each list contains all its items. GET /wishlists/{wishlistId} pages the items of one list.

​

Versions

Every response has an API-Version header (currently 1.0.0). New fields and endpoints are added to v1 without notice, so ignore fields you do not recognise. Breaking changes ship as a new base path (/api/v2).

When a version is deprecated, responses also include:

Deprecation: true
Sunset: Wed, 01 Sep 2027 00:00:00 GMT
Link: </api/v2>; rel="successor-version"

After the sunset date, the old version returns 410 VERSION_RETIRED. Show an “Update your app” message when you get it.

​

Idempotency

There are no idempotency keys. These calls are safe to repeat:

• PUT /products/{productId}/wishlists: sends the final state.
• POST /guest-wishlists/claim
• POST /wishlists/{wishlistId}/share-links: returns the same unused link.
• Bulk add with items[]: skips variants already in the list.

Adding a single product or creating a list again returns 409. Treat that as success if you are retrying.