GraphQL Admin API rate limits

The GraphQL Admin API's limits are based on a calculated cost for each query. This is in contrast to the REST Admin API, which limits an API client's requests based on the number of requests made over a set period of time. Every request is subject to throttling under our general limits. In addition, there are resource-based rate limits and throttles.

All requests that are made after the limit has been exceeded are throttled and an {errors: [{ message: "Throttled" }]} error is returned. Requests succeed again after enough space has accumulated in the bucket. Limits are calculated using the leaky bucket algorithm. You can use the GraphQL response to see the status of the throttle.

General API rate limits

The leaky bucket rate limits function like the REST Admin API's rate limiting system, but consider the cost of requests over time, rather than the number of requests. An app is given a bucket of 1000 cost points, with a leak rate of 50 cost points per second. This means that the total cost of your queries cannot exceed 1000 points at any given time, and that room is created in the app's bucket at a rate of 50 points per second. By making simpler, low-cost queries, you can make more queries over time.

The limit uses a combination of the requested and the actual query cost. Before execution begins, the app’s bucket must have enough room for the requested cost of the query. When execution is complete, the bucket is refunded the difference between the requested cost and the actual cost of the query.

Cost calculation

Every field in the schema has an integer cost value assigned to it. The cost of a query is the sum of the costs of each field.

Requested and actual cost

Shopify calculates the cost of a query both before and after query execution. The requested cost is based on the number of fields requested. The actual cost is based on the results returned, since the query can end early due to an object type field returning null, or connection fields can return fewer edges than requested.

Single query limit

A single query to the API cannot exceed a cost of 1000. This limit is enforced before a query is executed based on the query's requested cost.

Recommendations to avoid throttling errors

Design your app with API rate limits in mind to best handle request limits and avoid errors. To avoid rate limiting:

  • Vary time intervals of requests to avoid sending traffic in spikes.
  • Avoid requesting overlapping data.
  • Use the query response to balance your requests.

GraphQL response

The response includes information about the cost of the request and the state of the throttle. This data is returned under the extensions key:

"extensions": {
  "cost": {
    "requestedQueryCost": 101,
    "actualQueryCost": 46,
    "throttleStatus": {
      "maximumAvailable": 1000,
      "currentlyAvailable": 954,
      "restoreRate": 50

To get a detailed breakdown of how each field contributes to the requested cost, you can include the header 'X-GraphQL-Cost-Include-Fields': true in your request.

"extensions": {
  "cost": {
    "requestedQueryCost": 101,
    "actualQueryCost": 46,
    "throttleStatus": ...,
    "fields": [
        "path": [
        "definedCost": 1,
        "requestedTotalCost": 101,
        "requestedChildrenCost": 100

Resource-based rate limits

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

Sign up for a Partner account to get started.

Sign up