Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page
  • Authentication endpoint
  • Other endpoints
  • Read requests
  • Write requests
  • Response headers

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.

PreviousExternal tax calculatorsNextHandling errors

Last updated 10 months ago

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 (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 ).

If you're using Commerce Layer to interact with our Core API you can leverage the library to execute several API calls to a resource endpoint in batch and make sure not to hit the current rate limits ().

Authentication endpoint

All the requests to the /oauth/token endpoint to get an access token to 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

30

1 min

Other endpoints

All the 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 400 live reqs to the /api/bundles endpoint, 400 live reqs to the /api/skus endpoint, and 400 live reqs to the /api/prices endpoint, all within the same 1-min window — because it would result in a total of 1200 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)

Read 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

1000 (to all endpoints)

1 min

Test

Average

500 (to all endpoints)

1 min

Live

Burst

250 (per endpoint)

10 secs

Test

Burst

125 (per endpoint)

10 secs

Cacheable resources list
  • All types of promotions — /api/*_promotions

Uncacheable

Environment
Limit type
Max number of requests
Time window

Live

Average

200 (to all endpoints)

1 min

Test

Average

100 (to all endpoints)

1 min

Live

Burst

50 (per endpoint)

10 secs

Test

Burst

25 (per endpoint)

10 secs

Write requests

Write requests (performed via POST, PUT, PATCH, or DELETE 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

200 (to all endpoints)

1 min

Test

Average

100 (to all endpoints)

1 min

Live

Burst

50 (per endpoint)

10 secs

Test

Burst

25 (per endpoint)

10 secs

Response headers

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).

— /api/bundles

— /api/imports

— /api/markets

— /api/prices

— /api/price_lists

— /api/promotions

— /api/buy_x_pay_y_promotions

— /api/external_promotions

— /api/fixed_amount_promotions

— /api/fixed_price_promotions

— /api/free_gift_promotions

— /api/free_shipping_promotions

— /api/percentage_discount_promotions

— /api/skus

— /api/sku_options

— /api/stock_items

— /api/stock_locations

Read requests to all other endpoints (not listed ) are subject to the following rate limits:

You can get additional information you can use to avoid getting HTTP 429 Too many requests or to understand why your calls are being blocked by inspecting some specific headers included in the response:

The information in the headers above (number of requests, time window duration, etc.) refers to the Average only.

errors
above
limit type
JS SDK
SDK Utils
see example
authenticate
included in the response
resources
Bundles
Imports
Markets
Prices
Price list
Promotions
Buy X pay Y promotions
External promotions
Fixed amount promotions
Fixed price promotions
Free gift promotions
Free shipping promotions
Percentage discount promotions
SKUs
SKU options
Stock items
Stock locations
environment