Shopify Rate Limits

Overview

Shopify uses two distinct rate limiting systems: leaky bucket for REST and calculated query cost for GraphQL. This skill covers both with real header values and response shapes.

Prerequisites

• Understanding of Shopify's REST and GraphQL Admin APIs
• Familiarity with the

  @shopify/shopify-api

  library

Instructions

Step 1: Understand the Two Rate Limit Systems

REST Admin API -- Leaky Bucket:

The

X-Shopify-Shop-Api-Call-Limit

32/40

Retry-After

GraphQL Admin API -- Calculated Query Cost:

Every GraphQL response includes cost info in

extensions.cost

requestedQueryCost

actualQueryCost

throttleStatus

currentlyAvailable

THROTTLED

Step 2: Implement GraphQL Cost-Aware Throttling

Client-side rate limiter that tracks the query cost bucket and pre-emptively waits before sending requests that would be throttled. Updates available points from each response's

throttleStatus

See Cost-Aware Rate Limiter for the complete

ShopifyRateLimiter

Step 3: Implement Retry with Backoff for 429s

Generic retry wrapper handling both REST 429 responses and GraphQL THROTTLED errors. Uses

Retry-After

See Retry with Backoff for the complete implementation.

Step 4: Reduce Query Cost

Prune unused fields and lower

first:

requestedQueryCost

first: 250

first: 50

See Query Cost Reduction for before/after examples and the debug curl command.

Output

• Rate limit-aware client that prevents 429 errors
• Retry logic with proper backoff for both REST and GraphQL
• Optimized queries with lower calculated cost
• Debug headers for cost analysis

Error Handling

X-Shopify-Shop-Api-Call-Limit: 38/40

currentlyAvailable < 100

Retry-After: 2.0

errors[0].extensions.code: "THROTTLED"

Retry-After

restoreRate

Examples

Queue-Based Bulk Operations

For large data exports, use Shopify's bulk query API which bypasses rate limits entirely:

import PQueue from "p-queue";

const BULK_QUERY = `
  mutation bulkOperationRunQuery($query: String!) {
    bulkOperationRunQuery(query: $query) {
      bulkOperation { id status url }
      userErrors { field message }
    }
  }
`;

await client.request(BULK_QUERY, {
  variables: {
    query: `{
      products {
        edges {
          node {
            id title
            variants { edges { node { id sku price } } }
          }
        }
      }
    }`,
  },
});

Resources

• Shopify API Rate Limits
• REST Rate Limits
• GraphQL Rate Limits
• Bulk Operations