REST Admin API rate limits

To ensure our platform remains stable and fair for everyone, the REST Admin API is rate-limited. We use a variety of strategies to enforce rate limits. We ask developers to use industry standard techniques for limiting calls, caching results, and re-trying requests responsibly.

Anchor to Key figuresKey figures

The following are the key figures for rate limiting in the REST Admin API:

• Rate-limiting method: Apps can make a maximum number of requests per minute. For example, 40 API requests within 60 seconds. Each request counts equally, regardless of how much or how little data is returned.

• Standard limit: 2 requests/second

• Advanced Shopify limit: 4 requests/second

• Shopify Plus limit: 20 requests/second

• Shopify for enterprise (Commerce Components): 40 requests/ second

  Shopify might temporarily reduce API rate limits to protect platform stability. We will strive to keep these instances brief and rare. However, your application should be built to handle limits gracefully.

Anchor to The leaky bucket algorithmThe leaky bucket algorithm

All Shopify APIs use a leaky bucket algorithm to manage requests. The main points to understand about the leaky bucket metaphor are as follows:

• Each app has access to a bucket. It can hold, say, 60 “marbles”.

• Each API request tosses some number of marbles into the bucket.

• Each second, a marble is removed from the bucket (if there are any). This restores capacity for more marbles.

• If the bucket gets full, you get a throttle error and have to wait for more bucket capacity to become available.

  This model ensures that apps that manage API calls responsibly can maintain capacity to make bursts of requests when needed. For example, if you average 20 requests (“marbles”) per second but suddenly need to make 30 requests all at once, you can still do so without hitting your rate limit.

  The basic principles of the leaky bucket algorithm apply to all our rate limits, regardless of the specific methods used to apply them.

Anchor to Rate limitsRate limits

Calls to the REST Admin API are governed by request-based limits, which means you should consider the total number of API calls your app makes. In addition, there are resource-based rate limits and throttles.

REST Admin API rate limits are based on the combination of the app and store. This means that calls from one app don't affect the rate limits of another app, even on the same store. Similarly, calls to one store don't affect the rate limits of another store, even from the same app.

Limits are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. Requests succeed again after enough requests have emptied out of the bucket. You can see the current state of the throttle for a store by using the rate limits header.

The bucket size and leak rate properties determine the API’s burst behavior and request rate.

The default settings are as follows:

• Bucket size: 40 requests/app/store

• Leak rate: 2/second

  Plus

  The bucket size and leak rate is increased by a factor of 10 for Shopify Plus stores:

  • Bucket size: 400 requests/app/store
  • Leak rate: 20/second

  If the bucket size is exceeded, then an HTTP 429 Too Many Requests error is returned. The bucket empties at a leak rate of two requests per second. To avoid being throttled, you can build your app to average two requests per second. The throttle is a pass or fail operation. If there is available capacity in your bucket, then the request is executed without queueing or processing delays. Otherwise, the request is throttled.

  There is an additional rate limit for GET requests. When the value of the page parameter results in an offset of over 100,000 of the requested resource, a 429 Too Many Requests error is returned. For example, a request to GET /admin/collects.json?limit=250&page=401 would generate an offset of 100,250 (250 x 401 = 100,250) and return a 429 response.

  Caution

  Page-based pagination was deprecated in the REST Admin API with version 2019-07. Use cursor-based pagination instead.

Anchor to Rate limits headerRate limits header

You can check how many requests you’ve already made using the Shopify X-Shopify-Shop-Api-Call-Limit header that was sent in response to your API request. This header lists how many requests you’ve made for a particular store. For example:

In this example, 32 is the current request count and 40 is the bucket size. The request count decreases according to the leak rate over time. For example, if the header displays 39/40 requests, then after a wait period of ten seconds, the header displays 19/40 requests.

Anchor to Retry-After headerRetry-After header

When a request goes over a rate limit, a 429 Too Many Requests error and a Retry-After header are returned. The Retry-After header contains the number of seconds to wait until you can make a request again. Any request made before the wait time has elapsed is throttled.

Anchor to Resource-based rate limitsResource-based rate limits

The following REST Admin API resources have an additional throttle that takes effect when a store has 50,000 product variants. After this threshold is reached, no more than 1,000 new variants can be created per day.

In certain cases, Shopify needs to enforce rate limiting in order to prevent abuse of the platform. Therefore, your app should be prepared to handle rate limiting on all endpoints, rather than just those listed here.

Anchor to REST endpointsREST endpoints

• admin/products.json

• admin/products/{product_id}.json

• admin/products/{product_id}/variants.json

  If an app reaches API rate limits for a specific resource, then it receives a 429 Too Many Requests response, and a message that a throttle has been applied.

Anchor to Avoiding rate limit errorsAvoiding rate limit errors

Designing your app with best practices in mind is the best way to avoid throttling errors. For example, you can stagger API requests in a queue and do other processing tasks while waiting for the next queued job to run. Consider the following best practices when designing your app:

• Optimize your code to only get the data that your app requires.
• Use caching for data that your app uses often.
• Regulate the rate of your requests for smoother distribution.
• Include code that catches errors. If you ignore these errors and keep trying to make requests, then your app won’t be able to gracefully recover.
• Use metadata about your app’s API usage, included with all API responses, to manage your app’s behavior dynamically.
• Your code should stop making additional API requests until enough time has passed to retry. The recommended backoff time is 1 second.