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.

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

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.

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.