How Shopify's GraphQL Rate Limits Actually Work (and How to Stop Getting 429'd)

Originally published on the Kolachi Tech blog. Canonical link points back to the original.

If you treat Shopify's GraphQL Admin API like a REST endpoint and fire concurrent paginated requests, you will hit a wall of 429s fast. The reason is simple: Shopify doesn't rate-limit by request count. It limits by calculated query cost.

Once that clicks, the limits stop being a wall and become a budget. Here's the working model.

The core idea: cost, not count

REST charges the same for every call, whether you read one field or a thousand. Shopify scrapped that for GraphQL. The server runs static analysis on your query before execution, scores it by complexity, and deducts points from a bucket.

Cheap reads barely register. Heavy nested reads and writes cost real points. You can run many small queries or a few expensive ones, as long as you stay inside the budget.

How query cost is scored

The point values are fixed and deterministic, so you can predict cost before shipping.

Field type	Represents	Cost
Scalar / enum	A final value (id, title, email, boolean)	0 points
Object	A single related object (order.customer)	1 point
Connection	A paginated list (products, orders, variants)	2 points + 1 per returned item
Mutation	A write (create / update / delete)	10 points

Mutations cost more because they have side effects: DB writes, index updates, webhooks, emails.

Every response includes an extensions.cost object reporting both the requested cost (static analysis) and the actual cost (measured at runtime). The actual cost is often lower.

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 52,
      "actualQueryCost": 12,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 988,
        "restoreRate": 50
      }
    }
  }
}

Add the Shopify-GraphQL-Cost-Debug=1 header during development for a field-by-field breakdown.

Limits by plan

Plan tier	Bucket size	Restore rate
Standard (Basic, Shopify, Advanced)	1,000 points	50 points/sec
Shopify Plus	2,000 points	100 points/sec

Three things to burn into memory:

1. Every plan caps a single query at 1,000 points. Plus gives you a deeper bucket, not bigger queries. A query for 250 products × 100 variants each can blow past the ceiling without warning.
2. Restore is per second, not per minute. At 50 pts/sec you can run roughly one typical order query per second without throttling.
3. The bucket is scoped per app + store. One app's traffic never touches another app's budget on the same store.

The portability trap

A 1,500-point query works on Plus and fails instantly on a standard store. If your app spans multiple merchant tiers, cap max query cost at 1,000 points and rely on pagination, even when today's store runs Plus.

Read your usage before you get punished

Don't wait for a 429. Every response hands you throttleStatus. Check your next query's cost against currentlyAvailable before dispatching, and sleep if you're short.

A minimal local token-bucket guard in TypeScript:

type ThrottleStatus = {
  maximumAvailable: number;
  currentlyAvailable: number;
  restoreRate: number;
};

let bucket: ThrottleStatus = {
  maximumAvailable: 1000,
  currentlyAvailable: 1000,
  restoreRate: 50,
};

async function runQuery(query: string, estimatedCost: number) {
  // Refill estimate before dispatch
  if (bucket.currentlyAvailable < estimatedCost) {
    const deficit = estimatedCost - bucket.currentlyAvailable;
    const waitMs = Math.ceil((deficit / bucket.restoreRate) * 1000);
    await new Promise((r) => setTimeout(r, waitMs));
  }

  const res = await fetch(
    "https://your-store.myshopify.com/admin/api/2026-04/graphql.json",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Access-Token": process.env.SHOPIFY_TOKEN!,
      },
      body: JSON.stringify({ query }),
    }
  );

  const json = await res.json();

  // Trust the server's reported state over your local estimate
  if (json.extensions?.cost?.throttleStatus) {
    bucket = json.extensions.cost.throttleStatus;
  }

  return json;
}

Mirror Shopify's bucket in Redis if you have multiple workers, so they coordinate instead of each discovering the limit by failing.

Patterns that make throttling disappear

Request only the fields you need. If you need a title, don't pull the description and all 50 images. This compounds across millions of calls.

Back off cleanly on 429. Exponential backoff with jitter so retries don't stampede:

async function withBackoff<T>(fn: () => Promise<T>, max = 5): Promise<T> {
  for (let attempt = 0; attempt < max; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const base = 2 ** attempt * 100;
      const jitter = Math.random() * 100;
      await new Promise((r) => setTimeout(r, base + jitter));
    }
  }
  throw new Error("Max retries exceeded");
}

Prefer webhooks over polling. Polling burns points on data that hasn't changed. Subscribe to change events and poll only as a fallback.

Paginate deliberately. Connections cost 2 + 1 per item. Tune page size to your bucket: smaller pages cost less per call but add round trips.

Don't forget userErrors

The GraphQL API often returns 200 OK even when a mutation fails validation. The status code lies; the body tells the truth.

const { data } = await runQuery(mutation, 10);
const errors = data?.productUpdate?.userErrors ?? [];
if (errors.length) {
  // handle validation failures the HTTP status hid from you
  console.error(errors);
}

When to drop synchronous queries entirely

Single queries cap at 1,000 points. Some datasets just won't fit. That's what the Bulk Operations API is for.

Dataset	Approach
Under 1,000 records	Synchronous paginated queries
Over 1,000 records	Bulk Operations API
Deeply nested connections	Bulk Operations API
Real-time, small reads	Standard queries

Bulk runs async: submit a query, Shopify processes it in the background, you download a file. No max cost, no per-query rate limit. A bulk query can return 100k+ products without touching your bucket.

The architecture that survives production

• Webhooks first, polling only as fallback. Kills most read pressure.
• Local token bucket governs every outbound call.
• Bulk operations for anything over 1,000 records; synchronous queries stay lean.
• Observability across all of it, feeding throttle telemetry into a dashboard.

Get those four right and the Shopify API quota stops being a wall and becomes a budget you plan around.

---

Full write-up with more detail lives on the Kolachi Tech blog. If your team wants help building a throttle-resistant integration, that's our day job.

What patterns are you using to stay under the limit? Drop them in the comments.

Comments

[Luis]

Solid breakdown of Shopify’s cost-based throttling model—especially the framing of “budget instead of wall” makes it much easier to reason about in production systems.

A couple of additions that tend to matter in real-world high-throughput apps:

Concurrent workers are the real trap, not single queries: even well-optimized queries behave badly when 5–20 workers independently estimate cost and all “think” they’re safe. Centralizing the bucket (Redis or even Shopify’s returned currentlyAvailable as a shared truth) is usually the difference between stable throughput and random 429 spikes.
Cost estimation drift is inevitable: schema changes, added fields, or nested connections quietly increase actual cost vs estimated assumptions. Relying on static estimates alone tends to break over time unless you continuously re-validate against extensions.cost.
Bulk Operations as a de facto “escape hatch” is underrated here. A lot of teams try to micro-optimize pagination when the real win is just switching the access pattern entirely once data volume crosses a threshold.
One more subtlety: GraphQL “200 OK with userErrors” + throttling together creates failure modes that look like partial success unless you explicitly unify error handling + cost telemetry in one pipeline.

Overall, this is the right mental model shift—once teams treat cost like a first-class resource (CPU/memory equivalent), most Shopify integration instability disappears.

Curious if you’ve seen better results with pre-emptive cost prediction or just strictly reactive throttling via throttleStatus?