Rate limits

Requests are rate-limited per shop, using the same token bucket as AI / Agent access:

• Bucket capacity: 60
• Refill: 1 token per second
• Each API call consumes 1 token; reads and writes cost exactly the same

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

Staying within the limit

• Use the bulk endpoints. Every purchase-order line-item and lifecycle endpoint takes a list, so adding, updating, confirming, or receiving 40 lines is one token, not 40. Planning works the same way: add up to 500 plan items (200 on a new product plan) or delete up to 500 in one call. A loop over single items is the fastest way to empty the bucket.
• 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 the largest limit the endpoint allows (50 for lists, 250 for plan item pages) and follow the cursor rather than many small pages.
• Back off on 429. Wait the Retry-After interval and retry the same request.

Replays are free

A retry that is served from an Idempotency-Key replay costs no token; the stored answer is returned before the limit is even consulted. Retrying a keyed write can’t push you into 429.

Note

The per-shop limit protects the shop’s data store. It is independent of any edge-level (per-IP) protection your deployment may add for unauthenticated traffic.