> For the complete documentation index, see [llms.txt](https://api.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.shopwaive.com/reference/shopwaive-api-rate-limits.md).

# Shopwaive API rate limits

How many requests a second and a day the Shopwaive API takes, and what happens over a limit

To keep the platform stable and fair for everyone, the Shopwaive API limits how many requests it takes. Space your requests, cache what you read often, and retry responsibly.

***

## The Shopwaive API 2026-11 <a href="#the-shopwaive-api-2026-11" id="the-shopwaive-api-2026-11"></a>

Each request of the Shopwaive API 2026-11 counts against three limits at once: its key's, its store's (every key of the store together) and its source address's. Each limit is a number of requests a second, with a short burst above it.

| Requests                                                                  | Per key                   | Per store                  | Per source address        |
| ------------------------------------------------------------------------- | ------------------------- | -------------------------- | ------------------------- |
| Every request                                                             | 10 a second, bursts of 20 | 50 a second, bursts of 100 | 20 a second, bursts of 40 |
| Shopify store credit reads, also: `/api/2026-11/shopify-store-credit/...` | 5 a second, bursts of 10  | 10 a second, bursts of 20  | 5 a second, bursts of 10  |

A Shopify store credit read counts against its own row and against the first row.

**A day (UTC):**

* 50,000 requests for each key, and 50,000 for each store across its keys. Over that, a request answers `429` with the code [`daily_request_limit`](https://api.shopwaive.com/reference/errors.md#daily_request_limit), and `Retry-After` runs to midnight UTC.

**Over a limit a second**, a request answers `429` with the code [`rate_limited`](https://api.shopwaive.com/reference/errors.md#rate_limited) and a `Retry-After` header with the seconds to wait. Nothing is read or changed: wait, then send the same request again.

**Headers.** Once the key is known, every answer carries `X-RateLimit-Limit` (the key's burst for this request), `X-RateLimit-Remaining` (how many more it may send at once, right now) and `X-RateLimit-Reset` (the seconds until the key's limit is full again). Use them to slow down before you reach the limit.

{% hint style="info" %}
**Tip:** If your application needs a higher limit, contact us at <support@shopwaive.com>.
{% endhint %}

***

## Classic routes (deprecated) <a href="#classic-routes-deprecated" id="classic-routes-deprecated"></a>

The rest of this page gives the limits of the [classic routes](https://api.shopwaive.com/reference/rest-api-documentation.md), the requests with no version in the path.

### Limits by request

| Requests                                                                                           | Limit                                                         |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET`, `POST` and `PUT /api/customer`, `GET /api/actions`, `GET` and `POST /api/action/{actionid}` | 2 requests a second                                           |
| `DELETE /api/action/{actionid}`                                                                    | 20 requests a second                                          |
| Enterprise routes (below)                                                                          | 20 requests a second                                          |
| [Loyalty API](https://api.shopwaive.com/reference/rest-api-documentation/loyalty-api.md)           | 20 requests a second for each key, with short bursts up to 40 |

The limits above are for each API key. On every request here but the Loyalty API, all the keys of one store together can send three times a key's limit, for example 6 requests a second to the requests limited to 2.

{% hint style="info" %}
**Tip:** If your application needs a higher limit, contact us at <support@shopwaive.com>.
{% endhint %}

### Over the limit

A request over the limit gets HTTP `429` and a `Retry-After` header with the seconds to wait:

{% code overflow="wrap" %}

```json
{
  "error": "Too many requests. Limit requests to avoid throttling, max of 2 requests per second. If needed, upgrade to the Enterprise rate plan by contacting sales@shopwaive.com "
}
```

{% endcode %}

Answers from the limited `/api/customer` and `/api/action` routes carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Use them to slow down before you reach the limit.

### Segment deposits

A `PUT /api/customer` (or `PUT /v2/api/customer`) with a `segment_query` gives the amount to every customer in a Shopify customer segment. It has its own rules:

* It is available on the Shopwaive Checkout plan. On another plan it returns HTTP `403` with the reason `plan_required`, and nothing is changed.
* It needs an `Idempotency-Key` header. Without one it returns HTTP `400` with the reason `idempotency_key_required`.
* A store can send one a minute. A second one within the minute returns HTTP `429` with the reason `bulk_too_soon` and a `Retry-After` header.
* A store can deposit to 10,000 rows a day (UTC), and each segment deposit counts as 1,000. Over that, the request returns HTTP `429` with the reason `bulk_daily_limit` and a `Retry-After` header to the next UTC day. To raise the limit, contact <support@shopwaive.com>.
* A retry with the same `Idempotency-Key` on the same day is not counted again.
* HTTP `503` with the reason `bulk_check_unavailable` means the request could not be checked, and nothing was scheduled. Retry in a minute with the same `Idempotency-Key`.

### Enterprise limit

With an enterprise rate plan, our team gives you a key for the `X-Shopwaive-API-Enterprise` header. Send it, and add **/v2** in front of the route. Three routes have an enterprise version:

* `GET /v2/api/customer/{customer_email}`
* `POST /v2/api/customer`
* `PUT /v2/api/customer`

For example, to set a balance with the enterprise limit, send `POST /v2/api/customer` in place of `POST /api/customer`, with both headers and the `Idempotency-Key` header, as for `POST /api/customer`.

#### Header

<table><thead><tr><th width="313">key</th><th>value</th></tr></thead><tbody><tr><td>X-Shopwaive-Access-Token</td><td>Your Shopwaive API key, which starts with <code>swak_</code> (required)</td></tr><tr><td>X-Shopwaive-API-Enterprise</td><td>The enterprise key our team gives you (required)</td></tr></tbody></table>

***

### Avoiding rate limit errors

* Request only the data your app needs.
* Cache data that your app uses often.
* Spread your requests out in a queue.
* Catch errors. After a `429`, wait the seconds in `Retry-After` before you send the next request.
