> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-wishlyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```js theme={null}
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:

```json theme={null}
"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.

> [!NOTE]
>
> `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.