Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 55 ยท Admin GraphQL API

Rate Limits and Query Cost

Understand the Shopify Admin GraphQL cost model: calculated query cost, the leaky bucket, restore rate, THROTTLED errors and backoff, with runnable simulators.

Every API protects itself from clients that ask for too much. The Shopify Admin REST API counted requests. The Admin GraphQL API does something smarter, because one GraphQL request can ask for ten fields or ten thousand: it charges each request a cost in points, and it lets you spend points from a bucket that refills at a steady rate. If you understand that single idea, you can read every throttling message Shopify sends you and design an app that never gets stuck.

This lesson explains how the cost of a query is calculated, how to read the cost information that comes back with every response, how the leaky bucket works, and how to retry politely. All examples target Admin API version 2026-07, and the exact numbers (bucket sizes, per-plan rates) are the ones documented at the time of writing. Shopify adjusts them now and then, so treat the numbers as an illustration and always read the live values from the response, as shown below. If you need a refresher on queries and fields first, see GraphQL for Shopify Developers and Pagination with Cursors.

Real API calls cannot run on this site, so the requests below are read-only. The cost estimator and the bucket simulator are runnable stand-ins that follow the same ideas with simplified rules; they are not Shopify code.

Points, not requests

Each field in a query has a cost. The rules of thumb are:

  • A scalar field (a string, number, boolean, enum) costs 0.
  • An object field costs 1.
  • A connection (a paginated list) costs 2 plus the number of objects you ask for with first or last, plus the cost of whatever you select inside each object.
  • A mutation has a base cost of 10, plus the cost of the fields you select on its result.

The important property is that cost grows with the size of the answer you ask for, not with the number of round trips. Asking for first: 250 products with variants nested inside is expensive; asking for first: 5 is cheap.

There are two numbers to know:

  • The requested cost is calculated before the query runs, from the arguments you passed. It assumes every list is full.
  • The actual cost is what the query really used after it ran. If you asked for 250 products and the shop has 40, the actual cost is lower.

Shopify checks the requested cost against your bucket before running anything. After the query finishes it refunds the difference between requested and actual. That is why over-asking has a price even when the answer is small: your points are tied up for a moment.

A single query also has a hard ceiling on requested cost (1,000 points at the time of writing). A query above that limit is rejected outright, no matter how full your bucket is. The fix is never to wait; it is to ask for less per request and paginate.

Reading the cost from a response

Every response carries an extensions object next to data. This is a trimmed example of what a read-only request returns:

JSON
{
  "data": { "products": { "edges": [ ... ] } },
  "extensions": {
    "cost": {
      "requestedQueryCost": 52,
      "actualQueryCost": 14,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 986,
        "restoreRate": 100.0
      }
    }
  }
}

maximumAvailable is the size of your bucket, currentlyAvailable is how many points you can spend right now, and restoreRate is how many points per second flow back in. All three describe the app and shop pair making the call, not your whole app across every shop. Each installation has its own bucket.

The numbers depend on the merchant's plan: the standard plans have a bucket of 1,000 points restoring at 100 per second, and higher plans get proportionally larger buckets and faster restore rates. Your code should not hard-code any of this. Read throttleStatus from the most recent response and adapt.

While developing, you can ask Shopify for a per-field breakdown of the cost by sending the debug header Shopify-GraphQL-Cost-Debug: 1 with your request. It adds field-level detail to extensions.cost, which helps you find the expensive part of a query.

The leaky bucket

Picture a bucket with a hole in it, turned upside down. The bucket holds up to maximumAvailable points. Every request takes points out. Points drip back in at restoreRate per second until the bucket is full again.

flowchart LR
    R["Restore<br/>100 points per second"] --> B["Bucket<br/>capacity 1000"]
    B -->|"requested cost<br/>deducted up front"| Q["Your query runs"]
    Q -->|"refund of requested<br/>minus actual"| B

Points flow in at a fixed rate and are spent per query; the refund after execution returns unused points.

This model has two consequences. First, you can burst: a full bucket lets you send many queries in quick succession. Second, you cannot sustain that rate: over a long time, your average spending cannot exceed the restore rate. A job that needs 10,000 points of queries per minute on a 100-points-per-second plan (6,000 per minute) will be slowed down whatever you do.

Node.js Estimate the cost of a query

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first two queries are cheap, but nesting a 100-item list inside a 250-item list turns into tens of thousands of points. The lesson is the same as in the real API: nested connections multiply. Reduce first on the inner list, or fetch the inner data in a second query.

What happens when you run out

If your requested cost is larger than currentlyAvailable, the request is not executed. The response contains an error with a code:

JSON
{
  "errors": [
    {
      "message": "Throttled",
      "extensions": { "code": "THROTTLED", "documentation": "https://shopify.dev/api/usage/rate-limits" }
    }
  ],
  "extensions": {
    "cost": {
      "requestedQueryCost": 502,
      "actualQueryCost": null,
      "throttleStatus": { "maximumAvailable": 1000.0, "currentlyAvailable": 120, "restoreRate": 100.0 }
    }
  }
}

Notice that this arrives as a normal GraphQL error list, usually with an HTTP 200 status, so a client that only checks the status code will miss it. Always inspect errors[].extensions.code. A related code, MAX_COST_EXCEEDED, means the single query was over the per-query ceiling; waiting will not help, only a smaller query will. Shopify can also answer with HTTP 429 when you hammer the API at the network level, and then the Retry-After header tells you how many seconds to wait.

You can compute how long to wait without guessing. You need requested - currentlyAvailable more points, and the bucket gains restoreRate points per second:

Text
waitSeconds = (requestedCost - currentlyAvailable) / restoreRate

For the failed request above that is (502 - 120) / 100, which is 3.82 seconds. Add a small safety margin and retry. This is better than a blind exponential backoff because it uses the information Shopify gave you. Keep a cap on the number of retries so a bad query cannot loop forever.

Spending points wisely

  • Ask only for what you need. Every extra nested connection multiplies cost. Do not request fields "just in case".
  • Lower first for nested lists and paginate instead of nesting deeply.
  • Prefer bulk operations for big jobs. Reading or writing thousands of objects belongs in Bulk Operations, which runs on Shopify's side and does not spend your bucket the same way.
  • Prefer webhooks to polling. Asking "anything new?" every few seconds burns points for nothing. See Webhooks in Shopify.
  • Use a queue. Put API work into a job queue with a worker that respects the bucket, rather than calling the API from many places at once. The ideas in Architecture and Scaling apply directly.
  • Remember the bucket is per shop. A popular app serves many shops, and each has its own budget, so a worker should track the status per shop domain, not globally.
Node.js A leaky-bucket simulator with a polite client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run the simulator and watch the pattern: the first calls burst through, the third has to wait for the bucket to refill, and a request larger than the bucket can never succeed. A real worker does the same thing, except it reads currentlyAvailable from each response instead of keeping its own estimate.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Shopify compare against your bucket before it runs a GraphQL query?

    The requested cost assumes every list you ask for is full and is calculated before anything runs. After execution the difference to the actual cost is refunded to the bucket.
  2. 2. A response has errors[0].extensions.code equal to THROTTLED. What is the best next step?

    THROTTLED means the bucket does not hold enough points right now. Waiting (requested minus available) divided by the restore rate lets the bucket refill. Retrying at once only wastes calls.
  3. 3. Why does nesting products(first: 250) around variants(first: 100) get expensive so quickly?

    Connection cost scales with how many objects you request, and inner connections are counted once per outer object. Lower the inner first or fetch the inner data separately.
  4. 4. Which approach is best for reading every order in a store with hundreds of thousands of orders?

    Large exports are what bulk operations are for. They avoid spending your bucket page by page. The next lesson shows how they work.

Summary

  • GraphQL cost is measured in points: scalars cost 0, objects 1, connections 2 plus the number of objects requested, mutations start at 10.
  • The requested cost is checked before execution; the unused part is refunded afterwards. A single query has a hard ceiling.
  • Read extensions.cost.throttleStatus from every response: capacity, current balance and restore rate. Do not hard-code plan numbers.
  • A leaky bucket allows bursts but limits sustained throughput to the restore rate, and it is tracked per shop.
  • THROTTLED arrives as a GraphQL error: wait (requested - available) / restoreRate and retry with a retry cap; MAX_COST_EXCEEDED needs a smaller query.
  • Reduce cost with smaller pages, fewer nested lists, queues, webhooks instead of polling, and bulk operations for large jobs.

Next: Bulk Operations.