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 line-item and lifecycle endpoint takes a list, so adding, updating, confirming, or receiving 40 lines is one token, not 40. 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 limit=50 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.