Per token, per store
Calls are metered per token, in each store on its own: a token reaching three stores may call each at its full rate. The /v1/merchants calls, which name no store, are counted per token on their own.
- Rate. Unless the token sets its own, a token may make 600 calls a minute on each store.
- Quota. A token may also carry a quota of calls a day or a month, counted in UTC.
You set both when you create a token, and can change them later, on the merchant app’s API tokens page, which also shows each token’s calls on the store you are in. See authentication.
A POST /bulk call counts once, whatever its items, and runs at most 50 items. See bulk changes.
Past a limit
A call past a limit answers 429 with the problem type not_permitted and the reason limit. When the API knows when the limit lifts, the answer carries Retry-After in seconds: wait that long before calling again. Without it, back off and retry, with a growing wait and a bound on attempts.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12A refused call does nothing, so retrying it is always safe. The errors page has a helper that waits as long as the API asks, up to a minute. A spent quota’s Retry-After runs to the end of its day or month, so don’t wait it out in a loop.
New tokens from one network
Calls with a token the API hasn’t accepted in the last few minutes are also limited per network: about 30 a minute from one address (an IPv6 address counted by its /64), and 300 across an IPv6 /48. Past either, they answer 429 with the reason limit for up to a minute. A token in steady use is usually let through, so this only slows down a client trying many tokens, or a burst of first calls from many clients behind one address.
Staying within the limits
- Page with the largest
limita list takes rather than many small pages. - Use bulk changes for the operations that take them.
- Listen to webhooks instead of polling for changes.
- Give each job its own token, so one busy job doesn’t spend another’s rate.
- Keep license checks on your server for a while instead of checking on every request your software makes: each check counts like any call.