Muhammad Masad Ashraf

Posted on May 11 • Originally published at kolachitech.com

Handling Eventual Consistency in Shopify Integrations

#shopify #distributedsystems #webdev #backend

If you have built a Shopify integration before, you have hit this wall.

Your warehouse system shows 50 units. Shopify shows 45. An order comes in for 10 units. Now you have a problem you did not plan for.

This is eventual consistency at work. And it is one of the most common sources of production bugs in Shopify-connected systems.

This post walks through why it happens and exactly how to handle it.

What Eventual Consistency Actually Means

Eventual consistency means all systems will reflect the same data state eventually, but not at the same instant.

It sits at the opposite end of the spectrum from strong consistency, where every read returns the latest write. Strong consistency requires locking and synchronous coordination. That works fine on a single database. It does not scale to distributed commerce infrastructure serving millions of merchants.

Shopify prioritizes availability and performance over strict consistency. That is the right call for a platform at its scale. But it shifts the responsibility of handling consistency onto you, the integration developer.

Why This Happens in Shopify Integrations

There are five common causes:

Asynchronous webhooks
Shopify webhooks are fire-and-forget. There is no guaranteed delivery order. Retries create duplicates. If your endpoint is down, you miss events entirely.

API rate limits
When your sync job hits rate limits, some records update later than others. You end up with a window where data is partially synced.

Multiple integration points
Your store likely connects to an ERP, CRM, warehouse system, and marketing platform. Each one processes at a different speed and fails in different ways.

Network partitions
Any service in your stack can fail mid-sync. When it recovers, it has to reconcile against a Shopify state that moved on without it.

Concurrent writes
Two systems write to the same resource at the same time. Without conflict detection, the last write wins, which may not be the correct one.

The Strategies That Actually Work

1. Make Every Handler Idempotent

This is the most important one. If you do nothing else, do this.

When Shopify retries a webhook, your handler will receive the same event twice. Without idempotency, you process the order twice, deduct inventory twice, or send the confirmation email twice.

The fix is simple. Store a deduplication key before processing:

const dedupKey = `${topic}:${payload.id}`;
const alreadyProcessed = await db.events.findOne({ key: dedupKey });

if (alreadyProcessed) return res.sendStatus(200);

await db.events.insert({ key: dedupKey });
processEvent(payload);

Use the Shopify resource ID combined with the event topic as your key. Check it before doing any work. Write it as part of the same transaction if your database supports it.

2. Never Process Webhooks Synchronously

Your webhook endpoint should do one thing: accept the payload and return 200.

Processing the event inside the HTTP handler means any slowness or failure in your downstream systems causes Shopify to mark your endpoint as failed and retry, creating more duplicates.

Instead, push to a queue immediately:

app.post('/webhooks/orders-create', async (req, res) => {
  await queue.push({
    topic: req.headers['x-shopify-topic'],
    payload: req.body
  });
  res.sendStatus(200);
});

Your worker picks it up, processes it at its own pace, and retries independently from your HTTP layer.

3. Use Exponential Backoff with Jitter on Retries

When a downstream system is unavailable, retrying immediately makes things worse. All your queued workers collide on the same recovering service.

Use exponential backoff:

const delay = Math.min(
  BASE_DELAY * Math.pow(2, attemptNumber) + Math.random() * 1000,
  MAX_DELAY
);

The jitter (random component) spreads retries across a time window so workers do not all hit the service at the same second.

Always set a dead-letter queue for events that exhaust all retries. You need to know what failed and why.

4. Define Source of Truth Per Data Domain

Most multi-system conflicts come from two services both believing they own the same data.

Be explicit about ownership:

Data Domain	Source of Truth
Product catalog	Shopify or PIM
Inventory levels	Warehouse Management System
Order status	Shopify
Customer profiles	CRM
Fulfillment status	3PL or OMS

Once ownership is defined, all other systems become consumers. They read from the source of truth. They do not write back to it. This eliminates an entire category of conflicts.

5. Add a Polling Fallback Alongside Webhooks

Webhooks miss events. It happens. Endpoints go down, Shopify retries expire, network conditions cause silent failures.

Pair every webhook subscription with a scheduled polling job. The job fetches records where updated_at is greater than the last successful sync timestamp:

query {
  orders(first: 50, query: "updated_at:>2026-05-12T10:00:00Z") {
    edges {
      node {
        id
        updatedAt
        fulfillmentStatus
      }
    }
  }
}

Shopify's GraphQL API makes this efficient with cursor-based pagination and filtered queries. This job is your safety net for everything the webhook layer missed.

6. Use Optimistic Concurrency Control for Writes

When two systems write to the same resource, you need conflict detection.

Optimistic concurrency control works like this:

Read the resource and note the current version (use updated_at from Shopify)
Make your changes locally
Before writing, assert the version has not changed
If it has changed, re-fetch and retry

This prevents silent overwrites where a stale write replaces a more recent update from another system.

7. Set Freshness SLAs Per Data Type

Not all data needs to be equally fresh. Setting explicit staleness windows lets you make smarter sync decisions:

Data Type	Acceptable Staleness	Sync Method
Inventory counts	30-60 seconds	Webhook + polling fallback
Order status	Near real-time	Webhook with queue
Product descriptions	5-15 minutes	Scheduled batch
Customer loyalty points	1-2 minutes	Event-driven
Pricing rules	Near real-time	Webhook + cache invalidation

Once you have these defined, you can size your infrastructure appropriately instead of treating everything as equally urgent.

Monitoring Consistency Issues

Visibility is as important as the fix. Build these in from day one:

Lag metrics — Measure the time between a Shopify event firing and your system completing the action. Alert when it exceeds your SLA.

DLQ depth alerts — A dead-letter queue with growing depth means something is consistently failing. Treat it like an on-call alert.

Reconciliation jobs — Run periodic jobs that compare your local state against Shopify's current state. Log every discrepancy. Patterns reveal systemic problems.

Correlation IDs — Attach a unique ID to every event on ingestion and propagate it across all services. This lets you trace a single order through your entire stack.

Multi-Store Complexity

If you run multiple Shopify stores, consistency challenges multiply.

The standard approach:

Use a centralized sync coordinator that receives events from all stores and fans them out to downstream systems
Apply a global inventory buffer to absorb sync lag during peak periods
Use two-phase confirmation for high-value actions: soft-hold the resource first, confirm after all systems acknowledge

Quick Reference

Pattern	Problem It Solves
Idempotent handlers	Duplicate webhook delivery
Queue-based ingestion	Synchronous processing failures
Exponential backoff + jitter	Retry storms after outages
Source-of-truth ownership	Conflicting cross-system writes
Polling fallback	Silently missed webhook events
Optimistic concurrency	Stale write overwrites recent update
DLQ monitoring	Silent failures going undetected

Wrapping Up

Eventual consistency is not something you fix. It is something you design for.

Start with idempotency. Move event processing off the HTTP layer. Define who owns what data. Build in polling as a fallback. Measure lag continuously.

These patterns will not eliminate inconsistency windows. But they will stop those windows from becoming customer-facing bugs or business-critical failures.

Full guide with architecture patterns for multi-store setups and fault tolerance: