Shopify API Integration: REST vs. GraphQL and Rate Limits
A practical guide to Shopify API integration: choosing GraphQL vs REST, per-plan rate limits, webhooks vs polling, and idempotency.

A Shopify API integration means authenticating with an access token, then calling either the GraphQL Admin API or the legacy REST Admin API, and designing around Shopify's per-plan rate limits so retries, webhooks, and background jobs don't silently drop or duplicate data. Since April 1, 2025, new public apps must build exclusively against the GraphQL Admin API.
REST vs. GraphQL Admin API: Which Should You Use?
If you're starting a new Shopify API integration today, the answer is usually not in question: use the GraphQL Admin API. The REST Admin API has been a legacy API since October 1, 2024, and as of April 1, 2025, Shopify requires all new public apps to be built exclusively with the GraphQL Admin API. That doesn't mean REST has been shut off — apps already calling it can keep doing so, and some newer platform features are available only through GraphQL, which means even an existing REST-based integration will eventually need to add GraphQL calls alongside it, even without a hard migration deadline forcing the move.
The practical reason to prefer GraphQL for api integration shopify work goes beyond the mandate. GraphQL lets you request exactly the fields you need in a single round trip, instead of making several REST calls and discarding unused response data. For a sync job that pulls products, variants, and inventory together, that difference compounds quickly, and it changes how you think about cost rather than just request count.
If what you're actually building is a two-way sync between Shopify and a backend system — an ERP, a 3PL, or a CRM — the API choice is only one part of the architecture. We've written separately about evaluating a Shopify ERP integration — connector, iPaaS, or custom build — which matters as much as REST vs. GraphQL once you're past the "which API" question.
How Authentication Actually Works
Every authenticated Shopify API request follows the same basic shape: your app gets an access token scoped to what it needs, sends that token in a header, and Shopify checks it on each request. Which header depends on which API you're calling. The GraphQL Admin API and the Partner API both authenticate your app using the X-Shopify-Access-Token header. The Customer Account API is the exception — it authenticates a buyer rather than your app, using OAuth 2.0 with PKCE, and sends the token in a standard Authorization header. To keep the platform secure, apps request specific access scopes during install, and should only request the access they actually need.
Shopify also distinguishes between token types based on who or what the token represents. Offline access tokens are the default: they persist across sessions and are what you want for webhooks, scheduled jobs, and any background task that runs without a merchant actively looking at your app. Online access tokens are tied to a specific staff member's active session — request one explicitly when you need a request attributed to, and scoped by the permissions of, the person currently using your app. An online token expires after 24 hours or when that user logs out, whichever happens first. A third option, delegate access tokens, derive from your app's offline token but carry only a subset of scopes — useful when splitting an integration across subsystems that shouldn't all hold full access.
Because a leaked access token only exposes what it was granted, scoping tokens tightly is worth doing deliberately rather than requesting broad access "just in case." Shopify also lets public apps pair an expiring offline token with an IP allowlist, so the token only works for requests from addresses you specify — though it's worth understanding what Shopify's IP allowlist actually covers before treating it as your only layer of defense.
GraphQL Admin API Rate Limits: Cost-Based, By Plan
This is where a lot of shopify admin api rate limits confusion comes from, because the GraphQL and REST Admin APIs are throttled on completely different bases, and the two sets of numbers should never be quoted in the same breath.
The GraphQL Admin API doesn't count requests — it counts query cost, replenished continuously through a leaky-bucket model. Your available rate depends on the store's plan:
- Standard: 100 points/second
- Advanced Shopify: 200 points/second
- Shopify Plus: 1000 points/second
- Shopify for enterprise (Commerce Components): 2000 points/second
Every field in the schema carries a cost: scalars and enums cost 0, objects cost 1, mutations default to a cost of 10, and connections are sized by the first/last arguments you pass. A single query, regardless of plan, can never exceed 1,000 points of requested cost — large stores on Shopify Plus still hit that per-query ceiling even though their per-second budget is higher. Shopify calculates both a requested cost (before execution) and an actual cost (after execution, which can be lower if a connection returns fewer edges than requested), and refunds your bucket the difference.
If you need to see exactly where a query's cost comes from, add the Shopify-GraphQL-Cost-Debug: 1 header to get a field-by-field cost breakdown in the response — useful when a query feels more expensive than it should.
One important exception: bulk operations aren't subject to the single-query cost cap or the ordinary rate limits at all. If you're doing a large read or write — a full product catalog export, for instance — a bulk operation is usually the right tool rather than paginating through a cost-limited query.
REST Admin API Rate Limits: Request-Based, By Plan
If you're still on REST — maintaining an existing app rather than building new — the limiting model is different again: it's based on request count, not cost. REST uses a leaky bucket sized per app-per-store:
- Standard: bucket of 40 requests/app/store, leaking at 2 requests/second
- Advanced Shopify: 4 requests/second
- Shopify Plus: bucket of 400 requests/app/store, leaking at 20 requests/second (10x the standard bucket and rate)
- Shopify for enterprise (Commerce Components): 40 requests/second
Each request counts the same regardless of how much data it returns, which is part of why GraphQL's cost-based model tends to be more forgiving for integrations that mix small and large responses. REST also carries a resource-based throttle once a store has 500,000 product variants: no more than 10,000 new variants can be created per day across any API, not just REST, though this cap doesn't apply to Shopify Plus stores.
There's also a GET-specific limit worth knowing: if a page parameter pushes you past an offset of 100,000, you'll get a 429 regardless of your bucket state — a reminder that page-based pagination was deprecated starting with API version 2019-07 in favor of cursor-based pagination.
Reading the Throttle and Avoiding 429s
Both APIs tell you how close you are to the limit before you get throttled, if you know where to look. On REST, the X-Shopify-Shop-Api-Call-Limit header reports your current count against your bucket size, for example 32/40. On GraphQL, the extensions.cost.throttleStatus object in every response reports maximumAvailable, currentlyAvailable, and restoreRate, so you can back off before you're actually throttled rather than finding out from a failed request.
When you do exceed the limit, both APIs return an HTTP 429 with a Retry-After header stating how many seconds to wait before your next request will succeed. Honor that header rather than guessing at a backoff interval — retrying earlier just gets throttled again. For bulk workloads, remember that bulk operations sidestep this throttle model entirely, which is usually a better fix than tuning retry logic around a cost cap that doesn't need to apply to that job.
Webhooks vs. Polling — and Why You Need Both
Webhooks exist so you don't have to continuously poll Shopify for changes, but Shopify is explicit that webhook delivery isn't guaranteed: your app can miss events due to handler failures, downtime, or other issues on either side. Shopify's own recommendation is to pair webhooks with reconciliation jobs that periodically poll for whatever changed since the last run, typically using updated_at filters on the relevant GraphQL query. Webhooks give you near-real-time updates; the reconciliation job is what catches what webhooks missed. Shopify also doesn't guarantee webhook ordering within or across topics, so use the X-Shopify-Triggered-At header or the payload's updated_at field to sequence events rather than assuming delivery order reflects event order.
On the processing side, every HTTPS webhook delivery carries a base64 HMAC-SHA256 signature in the X-Shopify-Hmac-SHA256 header, computed from your app's client secret and the raw request body — verify it before trusting the payload. Because the same delivery can arrive more than once, use the X-Shopify-Webhook-Id header to detect and skip duplicates, and X-Shopify-Event-Id to correlate multiple deliveries that came from the same underlying merchant action. Your endpoint needs to return a 200 response within Shopify's one-second connection timeout and five-second total timeout; if a delivery fails outright, Shopify retries up to eight times over the following four hours before deleting the subscription.
Building this hybrid pipeline — webhooks for speed, polling for correctness, HMAC verification and deduplication so neither layer corrupts the other — is exactly the kind of work that's easy to get partially right and hard to get fully right. That's the core of what our Shopify integrations service is built around.
Idempotency: Keys and the @idempotent Directive
Network failures happen, and when a request to Shopify is interrupted in transit, you often won't know whether it succeeded before retrying. Idempotency keys solve that: generate a unique identifier (Shopify recommends a random UUID) and attach it to a mutation, and repeated requests with the same key execute only once no matter how many times you retry them.
Not every mutation needs one. Mutations that only update or delete an existing object are typically idempotent by definition. The ones that explicitly support idempotency keys tend to be the ones with side effects that aren't naturally safe to repeat — mutations that process payments, create subscription billing attempts, or otherwise capture revenue. subscriptionBillingAttemptCreate, for example, accepts an idempotencyKey directly as an input field.
Other mutations use a different mechanism: an @idempotent directive wrapped around the mutation call, with the key passed as a directive argument instead of an input field. The same directive also works inside bulk operations, where you pass the idempotency key as a field in each row of your JSONL input, applying idempotency per row rather than to the whole bulk job.
API Versioning: The Quarterly Cycle
Shopify ships a new stable API version every three months, released at 5pm UTC on the first day of the quarter, with date-based version names (2026-04, 2026-07, and so on). Each stable version stays supported for a minimum of 12 months, with at least nine months of overlap between consecutive versions — so you're never forced into a same-day migration. This versioning scheme covers the GraphQL Admin API, the Customer Account API, Function APIs, the Partner API, the Payments Apps API, the Storefront API, and Webhooks, whose payloads are versioned the same way as API responses.
It doesn't cover everything — Liquid, OAuth endpoints, the Ajax API, and the Catalog API are explicitly unversioned and can change at any time. Always specify an API version explicitly in your requests rather than relying on defaults, and track the version header Shopify returns on each response; if it doesn't match what you requested, your integration is targeting a version that's become inaccessible and Shopify has fallen forward to the oldest still-accessible stable version, which is worth catching before it becomes a silent compatibility problem.
If you want this integration built and maintained for you, talk to our team.
Frequently asked questions
Is the Shopify REST API deprecated?
Not deprecated outright, but legacy: the REST Admin API has been a legacy API since October 1, 2024, and since April 1, 2025 all new public apps must be built exclusively with the GraphQL Admin API. Apps already using REST can continue to call it.
What's the Shopify Admin API rate limit?
It depends on which API and which plan. The GraphQL Admin API is limited by query cost per second — 100 points/second on Standard, 200 on Advanced Shopify, 1000 on Shopify Plus, and 2000 on Commerce Components — with a single-query cap of 1,000 points on every plan. The REST Admin API is limited by request count — 2 requests/second on Standard up to 20 requests/second on Shopify Plus.
How do I avoid Shopify API 429 errors?
Watch the throttle headers before you hit the limit — X-Shopify-Shop-Api-Call-Limit on REST and extensions.cost.throttleStatus on GraphQL — and back off proactively. If you do get a 429, honor the Retry-After header instead of guessing at a delay, and move large reads or writes to bulk operations, which aren't subject to the single-query cost cap.
Should I use webhooks or polling for a Shopify integration?
Both. Webhooks give you near-real-time updates without constant polling, but Shopify doesn't guarantee webhook delivery, so it recommends pairing webhooks with periodic reconciliation jobs that poll for anything changed since the last run using updated_at filters.
Do I need an idempotency key for every Shopify API call?
No. Most update and delete mutations are idempotent by definition and don't need one. Idempotency keys matter for mutations with side effects that shouldn't be repeated accidentally, such as those that process payments or create subscription billing attempts — these either accept an idempotencyKey input field or use the @idempotent directive.