Agent skill · software engineering · jeremylongshore
shopify-rate-limits
Handle Shopify API rate limits for both REST (leaky bucket) and GraphQL
Why this skill is useful
Adds a complete implementation for handling Shopify API rate limits with retry logic and cost-aware throttling, which the AI cannot generate reliably on its own.
What it needs
Requires shopify account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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). See Retry with Backoff for the complete implementation. Step 4: Reduce Query Cost Prune unused fields and lower first: page sizes to reduce requestedQueryCost. A query dropping from first: 250 to first: 50 with fewer nested fields can go from ~5,500 to ~112 cost. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/shopify-rate-limits