APIs and integrations
Shopify GraphQL Admin API Query Cost and Rate Limits, Explained
In short
Shopify's GraphQL Admin API charges each query a calculated cost in points. Every app-and-store pair has a bucket that refills at a restore rate set by the plan, from 100 points a second on Standard to 2,000 on enterprise. One query may not cost more than 1,000 points. The response reports the cost and the bucket state.
How does Shopify work out the cost of a GraphQL query?
Each field costs a set number of points, and the query costs the maximum of the fields it could return. So the cost depends on the shape of the query, not on how many requests you send. The docs advise thinking about cost over time rather than request count, and running a query to find its true cost.
These are the default costs from the GraphQL Admin API rate-limits page.
- Scalars and enums: 0 points.
- Objects: 1 point.
- Interfaces and unions: the most expensive of the possible selections.
- Connections: sized by the
firstandlastarguments you pass. - Mutations: 10 points.
- Shopify may also set a manual cost on an individual field.
Checked against: source 1
What is the difference between requested and actual cost?
Requested cost comes from the fields you select and the first or last values on connections. Actual cost comes from the result, so it can be lower when objects are missing or a connection returns fewer edges than you asked for.
Before a query runs, the bucket must hold enough points for the requested cost. After it runs, Shopify gives back the difference between requested and actual cost. A single query may never request more than 1,000 points on any plan, and that check happens before execution.
A query under 1,000 points can still fail. The docs say large pages with many nested records may return an INTERNAL_SERVER_ERROR or a 5xx status, because totals and nested connections can require work on all related records. Adding the Shopify-GraphQL-Cost-Debug=1 header makes the response list the cost of each field.
Checked against: source 1
How fast does the bucket refill on each plan?
The limit applies to each app and store pair. One app does not use another app's allowance on the same store, and one store does not use another store's. The restore rate depends on the store's plan, and the REST Admin API uses the same plan tiers.
The docs say the bucket refills continuously, so short bursts are fine while your average cost stays under the restore rate. The GraphQL page gives no bucket size per plan.
The last column below is my own division of 1,000 by each restore rate, not a documented figure. The table also shows that the GraphQL rate is exactly 50 times the REST rate on every plan.
| Plan | GraphQL restore rate | REST leak rate | Time to refill 1 | 000 points |
|---|---|---|---|---|
| Standard | 100 points/s | 2 requests/s | 10 s | |
| Advanced Shopify | 200 points/s | 4 requests/s | 5 s | |
| Shopify Plus | 1,000 points/s | 20 requests/s | 1 s | |
| Shopify for enterprise (Commerce Components) | 2,000 points/s | 40 requests/s | 0.5 s |
What does the response tell my client?
Every GraphQL response carries an extensions.cost object with requestedQueryCost, actualQueryCost and a throttleStatus. The throttleStatus holds maximumAvailable, currentlyAvailable and restoreRate. The reference sample shows a maximum of 1,000 and a restore rate of 50, which matches no row of the plan table, so I read it as an example and not as a plan value.
The reference lists a THROTTLED error code as similar to a 429. It does not state the HTTP status of a throttled GraphQL response, and it says the GraphQL API can return 200 OK where REST would return a 4xx or 5xx. Read the errors array, not just the status.
The REST Admin API works differently. Each request counts the same, whatever data it returns. The X-Shopify-Shop-Api-Call-Limit header shows usage as current/bucket size, such as 32/40. A full bucket gives a 429 with a Retry-After header in seconds. REST is a legacy API as of 1 October 2024, and the docs say new public apps must use GraphQL.
What do the docs tell a client to do?
The limits overview and the GraphQL page agree on a short list.
- Request only the fields you need, and cache data you reuse.
- Queue and stagger requests so the rate is smooth, instead of sending bursts.
- Read the usage data in each response and slow down before the bucket is empty.
- Catch errors, do not retry blindly, and pause until enough time has passed. The overview recommends a backoff of one second.
- Use bulk operations for large reads and writes. The GraphQL page says they have no max cost or rate limits like single queries.
- Handle limits on every endpoint, and tolerate temporary reductions. Shopify says it may lower limits for a short time to protect the platform.
Which other limits can a query hit besides points?
Three limits sit outside the cost bucket. Array arguments accept at most 250 items on every Shopify API. Paginated lists stop at 25,000 objects, and that applies to count queries too. On REST, a page offset above 100,000 also returns a 429.
Stores with 500,000 product variants can create no more than 10,000 new variants a day on any API. The GraphQL page names productCreate, productUpdate and productVariantsBulkCreate as affected, and Shopify Plus stores are exempt.
What do the docs not say?
They give no bucket size per plan, no cost formula for connections beyond "sized by first and last", and no fixed HTTP status for a throttled GraphQL response. The restore rates and the REST bucket size of 40 can also change, since Shopify reserves the right to reduce limits.
This page leaves out the Storefront API, the Customer Account API and the Partner API, which have their own limits. Third-party posts that quote other bucket sizes are not covered either.
What else do people ask?
Is the 1,000-point limit a bucket size or a per-query cap?
It is a per-query cap that applies on every plan and is checked before the query runs. The docs give no per-plan bucket size.
Do mutations cost more than queries?
By default a mutation costs 10 points and an object 1 point, so a mutation costs more than a single object field. Shopify can set a manual cost on any field.
Should I still use the REST Admin API?
Shopify calls it a legacy API as of 1 October 2024 and says new public apps must be built on GraphQL, so plan on GraphQL.
Sources
- Shopify.dev, GraphQL Admin API rate limits, fetched 2026-11-19
- Shopify.dev, REST Admin API rate limits, fetched 2026-11-19
- Shopify.dev, API limits overview, fetched 2026-11-19
- Shopify.dev, GraphQL Admin API reference, fetched 2026-11-19
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. This page compares Shopify's own documents, fetched on 19 Nov 2026. I did not send test queries to Shopify for it, so nothing here is a measurement. It does not cover the Storefront, Customer Account or Partner APIs, bulk operation details, or any limit Shopify does not publish. Found a mistake? Tell me.