Rate limits

Requests are rate-limited per shop, using the same token bucket as AI / Agent access — REST calls and agent calls draw from one shared budget:

• Bucket capacity: 60 (burst ceiling)
• Refill: 1 token per second (sustained ~1 request/second)
• Each REST request consumes 1 token

When the bucket is empty, the API returns 429 RATE_LIMITED with a Retry-After header (seconds) and retryAfterMs in the error body.

Staying within the limit

• Don’t parallelise against one shop. The data store is single-threaded per shop — concurrent requests don’t complete faster and burn tokens. Issue calls sequentially.
• Page efficiently. Use a large pageSize and step through page rather than many small pages.
• Batch inventory writes. One PATCH …/inventory call can update many locations in one request — one token, not one per location.
• Back off on 429. Wait the Retry-After interval and retry the same request.

Note

Because the bucket is shared with AI / Agent access, a chatty assistant session and a REST integration running at the same time compete for the same 60-token budget. The per-shop limit protects the shop’s data store; it is independent of any edge-level (per-IP) protection.