Skip to content

Limits

Rate limits and quotas per app and per visitor, what files cost, and what happens past a limit.

Updated

Per app

Calls are counted per app, in each store: every token an app holds counts against that app’s limit, whichever customer it’s for. An app makes 600 calls a minute unless the merchant set it otherwise for the app, under Settings, Connections, API clients. The merchant may also give it a quota per day or per month, counted in UTC.

Per visitor

A publishable key’s rate limit holds per visitor instead: each address calling with it (an IPv6 address by its /64) gets the key’s calls a minute, so one visitor busy on your site never holds back the others, though visitors behind one shared address share it. Recording a page a visitor saw (Visits) counts too. A quota set on a key caps every visitor’s calls together, and since the key is public, anyone holding it can spend it.

Files

A private file costs two calls each time: asking for its URL, and fetching it. Asking again once the URL’s expires_at passed costs two more, though a video asked for with a publishable key holds 4 hours. Each range fetched is a fetch, ranges a video element asks for on its own included, though fetches of one URL from one address within a few seconds of the first may share its call. See Files and media.

Past a limit

A call past a limit answers 429 not_permitted with the reason limit, and a Retry-After header when the service knows when to retry. Wait that long, and slow down.

Refused credentials

Tokens a store refuses (unknown, expired, revoked or malformed) are also limited per network. Past about 60 a minute from one address (an IPv6 address by its /64), or 600 across an IPv6 /48, calls to that store with a token the store hasn’t accepted in the last few minutes answer 429 with the reason limit for up to a minute, never invalid_token. Keep the token and retry after Retry-After. A token in steady use keeps working.

Publishable keys a store refuses count the same way, so a page whose key was revoked answers 429 for a while past that many calls, while a key in use keeps working.

Email codes

Codes that prove a new address are limited per hour, a code sent again included, whatever app or page asked: 5 for one customer, 3 of them to one address, 20 to one address across customers, and 200 for the store across its customers. A customer may also ask for 5 address changes an hour from one network. Each day (in UTC), one customer may be sent 10 and one address 20. Past any of these, POST /contacts/change answers 429 with the reason limit until the hour or the day ends.

Subscriptions

A customer may cancel or resume one subscription 6 times in any 24 hours. Past that, POST /subscriptions/{subscription}/cancel and POST /subscriptions/{subscription}/resume answer 429 with the reason limit, and Retry-After says when the oldest of those frees. The store’s emails about them wait 2 minutes, so a change taken back at once sends only the latest.

Browsers

A call carrying an Origin header costs nothing more: reading which origins may read the answer isn’t counted. A preflight is kept 10 minutes per URL, so a page reading many products pays one preflight per product URL.

Bodies

A request body holds at most 16 MiB (413 past it), nests at most 64 levels deep, and holds at most 100000 objects and arrays and 100000 values (422 past them).

Type to search…

↑↓ navigate↵ selectEsc close