📦 Developer Reference

Shopify API Guide

Everything you need to understand Shopify's API surfaces — when to use each, how rate limits work, and how to scale from single calls to async bulk operations.

GraphQL Admin REST Admin Storefront API Bulk Operations Webhooks
🗂️

APIs at a Glance

Shopify exposes several API surfaces. New apps should default to the GraphQL Admin API.

GraphQL Admin API
Recommended
Full admin access — products, orders, customers, metafields. Cost-based rate limiting with per-plan point buckets.
REST Admin API
Legacy
Same domain as GraphQL, marked legacy Oct 2024. Only use if you must — migrate new work to GraphQL.
Storefront API
Buyer-facing
GraphQL for buyer-facing storefronts — products, collections, cart, checkout flows. No fixed req/min for real buyer traffic.
Bulk Operations + Webhooks
Async
High-volume async import/export and event-driven notifications from Shopify to your endpoint.
⚡

GraphQL Admin API

The recommended API for all admin CRUD. Rate limiting uses a calculated query cost model — not simple requests-per-second. Each app + store pair gets a bucket that restores over time.

Rate limits by plan

PlanPoints / secRestore rate
Standard10050 / sec
Advanced Shopify200—
Shopify Plus1,000—
Commerce Components2,000—
Hard cap: A single query can never exceed 1,000 cost points, regardless of plan. Input arrays are capped at 250 items each.

Throttle status in every response

Use the extensions.cost block to implement dynamic backoff — don't guess, read the signal Shopify gives you.

// Every GraphQL response includes this "extensions": { "cost": { "requestedQueryCost": 101, "actualQueryCost": 46, "throttleStatus": { "maximumAvailable": 1000, "currentlyAvailable": 954, // ← watch this "restoreRate": 50 } } }
🗄️

REST Admin API Legacy

Marked legacy as of October 2024. Uses a leaky bucket model based on raw requests-per-second rather than query cost.

PlanRequests / secBucket size
Standard240
Advanced Shopify4—
Shopify Plus20400
Commerce Components40—
Bucket full → 429 Too Many Requests with a Retry-After header. Always respect it before retrying.
🛍️

Storefront API

Buyer-facing GraphQL API — products, collections, carts, checkout. No fixed requests-per-minute for real buyer traffic.

Shopify throttles bots and malicious traffic with 430 Shopify Security Rejection. Higher limits are available for verified bots via Web Bot Auth.
📦

Bulk Operations

Designed for high-volume reads and writes that would exhaust normal query cost limits. Submit → poll → download. No HTTP connection held open.

No cost caps: Bulk operations don't share the single-query 1,000 point limit or standard rate limits. Always use bulk for "export all products/orders" or mass imports.

How it works

1
Submit a GraphQL mutation
This initial call is subject to normal cost limits. It queues the bulk job on Shopify's side.
2
Poll for completion
Shopify processes the job asynchronously in the background. Query the operation status periodically.
3
Download the result file
For queries: download a JSONL file. For imports: check completion status and any errors.

Use bulk operations for

  • Exporting all products, all orders, or all customers
  • Large catalog syncs or platform migrations
  • Any write that would drain your entire rate limit bucket in one go
🔔

Webhooks

Shopify POSTs to your HTTPS endpoint when a subscribed event occurs — orders/create, products/update, app/uninstalled, and more.

  • Respond with 2xx within a few seconds, or Shopify retries with backoff
  • Webhook deliveries do not count against your outbound API rate limits
  • Any Shopify API calls you make inside a webhook handler do count
  • Use for keeping external systems in sync without polling
⚙️

Shopify Functions

WebAssembly functions deployed via Admin GraphQL, invoked by Shopify at checkout runtime (discounts, shipping, payment customizations). You deploy — Shopify calls them when relevant events occur. No direct API call per buyer action.

🛡️

Global Limits

These apply across all APIs, regardless of plan.

250
Max items per input array
25k
Max paginated objects
1,000
New variants/day on 50k+ stores
Beyond 25,000 paginated items Shopify returns 25001 as a signal that more exist. Use filters to narrow down, or switch to bulk operations. The 1,000 variant/day limit does not apply to Shopify Plus.
🔀

Choosing Sync vs Async

⚡
Sync GraphQL
Low to moderate CRUD. Targeted queries. Creating or updating individual records.
📦
Bulk Operations
Mass exports, full catalog syncs, large imports. Would otherwise hit cost caps.
🔔
Webhooks
React to events without polling. Keep external systems in sync automatically.

Quick decision rule

  • Low to moderate volume + targeted → synchronous GraphQL Admin API
  • Would hit the 1,000-point query cap or drain your bucket → Bulk operations
  • Need to react to something that happened → Webhooks
Generated with Claude · Shopify API Guide · shopify.dev/docs
← Back to Portal