Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Shopwaive API rate limits

How many requests a second each part of the Shopwaive API takes, and what happens over the 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.


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

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.

Tip: If your application needs a higher limit, contact us at support@shopwaive.com.

Over the limit

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

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

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.

key
value

X-Shopwaive-Access-Token

Your Shopwaive API key, which starts with swak_ (required)

X-Shopwaive-API-Enterprise

The enterprise key our team gives you (required)


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.

Last updated