Rate limits
Requests are rate-limited by two token buckets, the same ones AI / Agent access uses:
| Bucket | Capacity | Refill |
|---|---|---|
| Per shop | 120 | 2 tokens per second |
| Per API key | 60 | 1 token per second |
A call takes its cost from both buckets at once; if either is short, the call is refused and neither is charged.
- Most calls cost 1 token; reads and writes cost the same.
GET /forecast-views/{id}/rowscosts 15 tokens per call, whatever itslimit: every call recomputes the view and reads stock fresh. A call above 1,000 rows still costs 15, although Logistified reads it in 1,000-row pages. With one key that is four calls in a burst, then one every 15 seconds.
When a bucket is empty, the API returns 429 RATE_LIMITED with a Retry-After header (seconds).
One heavy call per shop at a time
Section titled “One heavy call per shop at a time”A forecast-view computation runs alone per shop. While one is running, a second one, from REST or
from AI / Agent access, gets 429 RATE_LIMITED with error.data.code = SHOP_BUSY and
Retry-After: 15. Wait, then send the same request again. Run forecast-view pulls one after
another, never in parallel.
A call above 1,000 rows runs its pages one by one: a heavy call that starts between two pages
makes the rest of that call answer 429 SHOP_BUSY. Retry the whole call.
Staying within the limit
Section titled “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
limitthe endpoint allows (50 for lists, 250 for plan item pages) and follow thecursorrather than many small pages. - Read a whole forecast view in one call. Forecast views are the exception to cursor paging:
separately requested pages are computed separately and can shift, so a sync reads each view with
limit=4000, one call for a view of up to 4,000 rows, and never stitches calls together. A larger view is split into disjoint product-filtered views. See Syncing forecast views. - Back off on 429. Wait the
Retry-Afterinterval and retry the same request.