REST Admin API rate limits

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.

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.

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

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.

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.

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.

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.

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

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.