Rate limits: designing an integration that does not throttle

The single most useful fact about Shopify rate limits is not a number. It is that the bucket belongs to your app on that store, and nothing in the platform knows which of your processes deserves it more. The REST documentation states the limit plainly as requests per app, per store. The GraphQL bucket works the same way, which is why throttleStatus.currentlyAvailable can be near zero on a call your service has not made — another one of your own processes drained it.

This is where most throttling incidents actually begin. A store has a nightly catalogue sync, a webhook consumer writing fulfilment updates, a customer service tool that reads orders on demand, and a reporting job somebody scheduled hourly. Each was built in isolation, each behaves well on its own, and together they spend a budget none of them can see. The symptom is intermittent and lands on whichever job happens to be running when the others peak — which is why the ticket always blames the wrong component.

So the first architectural decision is not the retry policy. It is: what does the budget for this store belong to, and which component owns it?

The highest-value change in most throttling reviews is deleting a loop. A job that asks every fifteen minutes whether any order has changed is spending budget continuously to discover, most of the time, that nothing has. Multiply that by four integrations and a store’s entire budget goes on questions with the answer “no”.

The replacement is the boring one: subscribe to the webhook topic and consume events. The read budget then gets spent on the records that actually changed, and it scales with the store’s real activity rather than with your polling interval. Webhooks come with their own failure mode — delivery is not guaranteed and retries mean you will process some events twice — which is a design problem worth solving once rather than a reason to keep polling.

Where webhooks are not the answer, bulk operations usually are. Anything whose shape is “every product” or “every order since the beginning” should be submitted as an asynchronous bulk operation rather than paged, because bulk operations are not subject to the per-query cost cap or the ordinary rate limits. A paginated full-catalogue read is a recurring incident on any store large enough to care.

What is left after removing polling and bulk work is usually small: targeted reads, targeted writes, and reconciliation. That residue fits inside the budget comfortably on any plan.

When several jobs must share a budget, the fix is to make them share a lane. Route every Admin API call for a given store through one queue, give the queue a concurrency limit, and have the worker read extensions.cost.throttleStatus from each response so the queue knows what is left rather than guessing.

That one pattern removes most of the failure modes. Jobs stop competing because they are serialised. Backpressure becomes visible — a queue depth you can graph — instead of arriving as a scatter of 429s in an error tracker. And the pacing adapts on its own when a merchant upgrades to Plus and the restore rate jumps tenfold, because the worker is reading the real restoreRate rather than a delay somebody tuned against a development store two years ago.

Give the queue priorities while you are there. An interactive request — a support agent opening an order, a customer checking a status — should not wait behind 40,000 queued catalogue writes. Two lanes with a reserved share of the budget for the interactive one costs very little to build and is the difference between a slow batch job and a broken product.

The one thing to resist is scaling horizontally without a shared limiter. Four workers each politely observing the throttle status they personally saw will still collectively overrun the bucket, because none of them knows about the other three. The limiter has to live outside the worker.

You will still be throttled occasionally, and that is fine — the goal is an integration that degrades rather than one that never hits the limit. What matters is what happens next.

Both Admin APIs return 429 Too Many Requests. REST includes a Retry-After header carrying the seconds to wait, and Shopify’s general guidance gives one second as the recommended backoff. On GraphQL you can do better than a fixed wait: throttleStatus gives maximumAvailable, currentlyAvailable and restoreRate, so the wait is simply the shortfall divided by the restore rate. For Storefront API checkout throttling, Shopify recommends a request queue with an exponential backoff algorithm.

Two things to get right regardless of the API. Retries need jitter, or a burst of failures becomes a synchronised burst of retries that reproduces the problem exactly one second later. And any retried mutation needs to be safe to replay, because at some point one will be sent twice — the same idempotency problem as webhook redelivery, and worth designing once for both.

If you are hunting for what a query actually costs, the Shopify-GraphQL-Cost-Debug=1 header returns a per-field breakdown. That is a faster route to the expensive nested connection than reading the query and reasoning about it.

When a client brings us an integration that throttles, we do not start with the code. We start with an inventory: every process that talks to this store, what it does, how often, and who owns it. That list is usually longer than anyone expected and contains at least one job whose original purpose nobody can remember.

Then three questions. Which of these is polling for something a webhook would deliver? Which is reading the whole catalogue when it needs a delta? And which two are running at the same time, every night, because they were both scheduled for midnight by different people?

The fix that follows is almost never a bigger plan. Upgrading to Plus multiplies the restore rate, and an integration with the wrong shape will find a way to exhaust that too — the same job, finishing its unnecessary work ten times faster, on a store ten times larger.

• Custom Shopify apps and back ends
• The Admin GraphQL API: pagination, cost and bulk operations
• Webhooks, retries and the orders you never processed