APIs, Webhooks, and Choosing the Right Tool

Two walls remain from Lesson 1. Flow cannot reach systems Shopify does not know about, and it cannot do bulk work. Functions cannot either; they answer one bounded question inside checkout.

Everything else runs through the API, and that means writing a real integration. This lesson covers what that involves and, more importantly, how to decide whether you should.

Three pieces make up the surface:

• The Admin GraphQL API: read and write store data programmatically.
• Webhooks: have Shopify tell your system when something happens, rather than asking repeatedly.
• Bulk operations: move large datasets without fighting rate limits.

A warning worth giving up front. This is the most powerful option and the most expensive one. Flow is a workflow you can read in the admin. A Function is a bounded decision. An API integration is software you now own: it needs hosting, monitoring, error handling, and someone to fix it at 2am when it breaks during a sale. That cost is permanent and it is routinely underestimated.

So the real skill this lesson teaches is not the API. It is knowing when not to use it, which is why it ends in a decision framework rather than more syntax.

Shopify's Admin API is GraphQL, and its rate limiting is the part that shapes how you write code against it. Most APIs count requests. Shopify counts work.

The model is a calculated query cost on a leaky bucket. Your app has a bucket of points that refills over time. Each query costs points according to how much it asks for, so requesting one product costs far less than requesting a thousand products with all their variants.

The accounting has a detail worth knowing:

• Before execution, your bucket must have capacity for the query's requested cost, an estimate based on what you asked for.
• After execution, the bucket is refunded the difference between the requested cost and the actual cost.
• A single query may not exceed 1,000 points, regardless of your plan, enforced before execution based on requested cost.

That refund rule is not trivia, it changes how you write queries. Ask for first: 250 and you are charged as if all 250 come back; if only 3 exist, you are refunded. But the requested cost is what must fit in the bucket, so a greedy query can be rejected for capacity it never actually needed.

The design intent is sensible: make expensive questions cost more. It pushes you toward asking for exactly what you need, which is also the reason for GraphQL. The practical consequences are consistent: request only the fields you use, page deliberately, and expect to handle throttling as a normal condition rather than an error, because at any real volume you will meet it.

Polling an API to ask "anything new?" is wasteful and slow. Webhooks invert it: Shopify calls your endpoint when something happens. You register a URL for a topic, an order is created, and Shopify posts you the payload.

Then comes the detail that decides whether your integration is correct or quietly broken. Shopify operates an at-least-once delivery model, not exactly-once. Your application might receive the same event multiple times.

This is not a defect, it is the honest engineering trade-off any distributed system faces. If Shopify sends an event and does not hear a confirmation, it cannot know whether you processed it and the acknowledgement was lost, or you never received it. Guaranteeing exactly-once delivery across an unreliable network is famously not achievable in general, so the platform chooses the safe failure: send again. Better a duplicate than a lost order.

Which moves the burden to you. Your handler must be idempotent: processing the same event twice must produce the same result as processing it once. Otherwise a retried webhook charges a customer twice, sends two emails, or creates two records in your warehouse system.

Shopify gives you the tool: every delivery includes an X-Shopify-Webhook-Id header. Use it as your deduplication key. Record the IDs you have processed and ignore repeats.

The lesson generalizes to every webhook you will ever consume: assume duplicates and design for them. "It worked in testing" is not evidence, because duplicates arrive under load and failure, exactly when you are not watching.

Now the other wall: "update 40,000 products." Doing that through normal queries means tens of thousands of calls, each drawing from your cost bucket, taking hours and colliding with throttling constantly. It is the wrong shape of tool.

Bulk operations, available only through the GraphQL Admin API, solve it by inverting the model. Instead of you pulling data request by request, you hand Shopify the job and let it run asynchronously:

• bulkOperationRunQuery for reading. You submit a query, Shopify executes it in the background across the whole dataset and produces a JSONL file you download when it finishes.
• bulkOperationRunMutation for writing. You upload a JSONL file of input data, and Shopify executes your mutation once per line, asynchronously.

The crucial property is the rate-limit treatment: your GraphQL requests to start and poll the operation count as normal API calls and are subject to rate limits, but the bulk operation's own execution is not. So the work itself runs outside your cost bucket. That is the entire point, and it is why fighting rate limits with a loop is the wrong instinct.

On concurrency, API versions 2026-01 and higher allow up to five bulk query operations running concurrently per shop, so you can process several large datasets at once rather than serializing them.

The shift in thinking is the valuable part: stop asking repeatedly and start submitting a job. Bulk work is a batch problem, and treating it as a fast loop of small requests is how integrations end up slow, throttled, and fragile.

Put the pieces together on a realistic job: sync paid orders into an external warehouse system.

1. Register a webhook   topic: orders/paid  ->  https://you/hooks

2. Shopify POSTs the order to your endpoint

3. Your handler:
     id = headers["X-Shopify-Webhook-Id"]
     if seen(id): return 200        <-- idempotency, the duplicate case
     mark_seen(id)
     enqueue(order)                 <-- do the slow work elsewhere
     return 200 quickly             <-- ack fast or be retried

4. A worker pulls from the queue and calls the warehouse API.
   Fails? Retry with backoff. The webhook is already acked.

5. Nightly reconciliation:
     bulkOperationRunQuery over yesterday's orders
     compare against the warehouse, repair gaps

Four design choices there are the whole lesson.

Deduplicate on the webhook ID, because at-least-once delivery guarantees you will see repeats.

Acknowledge fast, work later. Your endpoint's only job is to accept the event. Doing slow work inline risks a timeout, which Shopify reads as failure and retries, producing more duplicates and a worse problem.

Retry the warehouse call, not the webhook. Once acked, the event is yours to keep safe.

Reconcile in bulk. This is the step people skip and regret. Webhooks can be missed, endpoints have outages, and networks fail. A nightly bulk query that compares state and repairs gaps turns a silent divergence into a self-healing system. Event streams tell you what changed; bulk queries tell you what is true. You want both.

You now have four options. Choosing well matters more than any implementation detail, because the wrong choice costs you for years.

The rule, in order:

1. Can Flow do it? Then stop. No code, no hosting, no maintenance, and legible to everyone.
2. Is it a checkout decision? Functions. Check the app store first, tiered discounts and shipping rules are solved problems.
3. Does an app already do it? A subscription is almost always cheaper than building and maintaining an integration.
4. Only then, build. When the need is genuinely specific to your business and genuinely outside the platform.

The failure mode is predictable and expensive: a developer reaches for the API because it is familiar and unlimited, and the store ends up with a custom service that duplicates what Flow does natively, needs a server, and breaks when its author leaves.

The throughline of the cursus: Shopify gives you layered extension points, and the skill is picking the shallowest one that works. Flow reacts, Functions decide, APIs integrate. Reaching deeper than necessary is not sophistication, it is unnecessary permanent cost, and the store still has to run at 3am on Black Friday.

Work down the layers: use Flow if a store event and Shopify's own data suffice, Functions if a checkout decision must change as it happens, an existing app if the need is common, and only build an API integration when the need is genuinely external, custom, or bulk.