| name | shopify-rate-limits |
| description | Handle Shopify API rate limits for both REST (leaky bucket) and GraphQL (calculated query cost).
Use when hitting 429 errors, implementing retry logic, or optimizing API request throughput.
Trigger with phrases like "shopify rate limit", "shopify throttling",
"shopify 429", "shopify THROTTLED", "shopify query cost", "shopify backoff".
|
| allowed-tools | Read, Write, Edit |
| version | 2.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","ecommerce","shopify"] |
| compatibility | Designed for Claude Code |
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:
| Plan | Bucket Size | Leak Rate |
|---|
| Standard | 40 requests | 2/second |
| Shopify Plus | 80 requests | 4/second |
The X-Shopify-Shop-Api-Call-Limit header shows your bucket state (e.g., 32/40 means 32 of 40 slots used). When full, you get HTTP 429 with Retry-After header.
GraphQL Admin API -- Calculated Query Cost:
| Plan | Max Available | Restore Rate |
|---|
| Standard | 1,000 points | 50 points/second |
| Shopify Plus | 2,000 points | 100 points/second |
Every GraphQL response includes cost info in extensions.cost with requestedQueryCost (worst-case estimate), actualQueryCost (real cost, often much lower), and throttleStatus (available points and restore rate). When currentlyAvailable drops to 0, you get 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 class.
Step 3: Implement Retry with Backoff for 429s
Generic retry wrapper handling both REST 429 responses and GraphQL THROTTLED errors. Uses Retry-After header when available, otherwise exponential backoff with jitter (max 30s).
