Rate limits

Information about the restrictions on the number of times a user or client can access Commerce Layer API endpoints within a specified period of time.

To protect our platform against API misuse or overuse and ensure the system is available for all our users we adopt a rate-limiting strategy, differentiated by environment (test or live), HTTP method, and types of resources involved.
IP addresses that exceed the following rates will be blocked until the frequency of the specific call drops below the allowed limit. Please note that the count on the number of requests is never reset: you must consider the time intervals as sliding time windows (that's why no X-Ratelimit-Reset header is included in the response).
Authentication endpoint
All the requests to the /oauth/token endpoint to get an access token to authenticate your API calls are never cached and are subject to stricter rate limits, regardless of the environment:
Environment
Max number of requests
Time window
Live, Test
20
1 min
Other endpoints
All the resources endpoint can be grouped into two main classes depending on whether they could be cached or not (cacheable or uncacheable). Two kinds of rate limits are applied to the IP with which you perform the calls to the /api/* endpoints:
Average — the number of requests is calculated considering the sum of the requests sent to all the resource endpoints of the specific class in the related time window (e.g. you cannot send 300 live reqs to the /api/bundles endpoint, 300 live reqs to the /api/skus endpoint, and 300 live reqs to the /api/prices endpoint, all within the same 1-min window — because it would result in a total of 900 reqs / 1 min).
Burst — the number of requests is calculated on each single resource endpoint of the specific class (e.g. you can send 25 test reqs to the /api/addresses endpoint, 25 test reqs to the /api/orders endpoint, and 25 test reqs to the /api/line_items endpoint, all within the same 10-sec window)
GET requests
Read requests (performed via GET,  HEAD, or OPTIONS HTTP methods) are subject to different rate limits based on the type of resource.
Cacheable
Please find below the list of cacheable resources. Read requests to the related endpoints are subject to the following rate limits:
Environment
Limit type
Max number of requests
Time window
Live
Average
750 (to all endpoints)
1 min
Test
Average
375 (to all endpoints)
1 min
Live
Burst
250 (per endpoint)
10 secs
Test
Burst
125 (per endpoint)
10 secs
Cacheable resources list
​Bundles — /api/bundles
​Imports — /api/imports
​Markets — /api/markets
​Prices — /api/prices
​Price list — /api/price_lists
​Promotions — /api/promotions
All types of promotions — /api/*_promotions
​External promotions — /api/external_promotions
​Fixed amount promotions — /api/fixed_amount_promotions
​Fixed price promotions — /api/fixed_price_promotions
​Free gift promotions — /api/free_gift_promotions
​Free shipping promotions — /api/free_shipping_promotions
​Percentage discount promotions — /api/percentage_discount_promotions
​SKUs — /api/skus
​SKU options — /api/sku_options
​Stock items — /api/stock_items
​Stock locations — /api/stock_locations
Uncacheable
Read requests to all other endpoints (not listed above) are subject to the following rate limits:
Environment
Limit type
Max number of requests
Time window
Live
Average
150 (to all endpoints)
1 min
Test
Average
75 (to all endpoints)
1 min
Live
Burst
50 (per endpoint)
10 secs
Test
Burst
25 (per endpoint)
10 secs
POST and PATCH requests
Write requests (performed via POST or  PATCH HTTP methods) to any endpoint (regardless of whether the related resource falls into the cacheable or uncacheable category) are subject to the following rate limits:
Environment
Limit type
Max number of requests
Time window
Live
Average
150 (to all endpoints)
1 min
Test
Average
75 (to all endpoints)
1 min
Live
Burst
50 (per endpoint)
10 secs
Test
Burst
25 (per endpoint)
10 secs
Response headers
You can get additional information you can use to avoid getting HTTP 429 Too many requests errors or to understand why your calls are being blocked by inspecting some specific headers included in the response:
Header
Description
X-Ratelimit-Limit
The maximum number of requests allowed in the sliding time window.
X-Ratelimit-Interval
The total duration of the sliding time window (in seconds).
X-Ratelimit-Remaining
The number of allowed requests remaining in the current time window (0 in case of HTTP 429 errors).
The following headers are still included in the response, but they are deprecated ⚠
 and will be soon removed (please make sure to stop relying on them and update your integration/app to use the ones above):
Header
Description
Note
X-Ratelimit-Count
The number of requests sent so far in the current time window.
Use X-Ratelimit-Remaining instead (corresponding to the difference between X-Ratelimit-Limit and X-Ratelimit-Count).
X-Ratelimit-Period
The total duration of the sliding time window (in seconds).
Use X-Ratelimit-Interval instead.

Environment	Max number of requests	Time window
Live, Test	20	1 min

Environment	Limit type	Max number of requests	Time window
Live	Average	750 (to all endpoints)	1 min
Test	Average	375 (to all endpoints)	1 min
Live	Burst	250 (per endpoint)	10 secs
Test	Burst	125 (per endpoint)	10 secs

Environment	Limit type	Max number of requests	Time window
Live	Average	150 (to all endpoints)	1 min
Test	Average	75 (to all endpoints)	1 min
Live	Burst	50 (per endpoint)	10 secs
Test	Burst	25 (per endpoint)	10 secs

Environment	Limit type	Max number of requests	Time window
Live	Average	150 (to all endpoints)	1 min
Test	Average	75 (to all endpoints)	1 min
Live	Burst	50 (per endpoint)	10 secs
Test	Burst	25 (per endpoint)	10 secs

Header	Description
`X-Ratelimit-Limit`	The maximum number of requests allowed in the sliding time window.
`X-Ratelimit-Interval`	The total duration of the sliding time window (in seconds).
`X-Ratelimit-Remaining`	The number of allowed requests remaining in the current time window (`0` in case of HTTP `429` errors).

Header	Description	Note
`X-Ratelimit-Count`	The number of requests sent so far in the current time window.	Use `X-Ratelimit-Remaining` instead (corresponding to the difference between `X-Ratelimit-Limit` and `X-Ratelimit-Count`).
`X-Ratelimit-Period`	The total duration of the sliding time window (in seconds).	Use `X-Ratelimit-Interval` instead.

External tax calculators

Handling errors

Last modified 21d ago

Rate limits

Authentication endpoint

Other endpoints

`GET` requests

Cacheable

Uncacheable

`POST` and `PATCH` requests

Response headers