Separate a repeated delivery from a legitimate new order or update. Duplicate prevention requires understanding what the incoming identifier represents and what the receiving action actually does. A customer email, a webhook ID and a commerce order ID are not interchangeable keys.
This is a design and verification worksheet, not tested integration code or a guarantee that an arbitrary connector creates orders exactly once.
Map the identifiers and writing routes
Record each route that can create an order: the store’s intended checkout, an external integration, an import or permitted manual entry. For external sources, identify the stable sale/order reference and how it maps to the resulting Shopify order. Keep separate purchases and subscription renewals distinguishable from updates to an existing order.
| Identifier | What it represents | What it does not establish |
|---|---|---|
| Source order/sale reference | The record in the originating system | Automatic duplicate protection at the destination |
| Shopify order ID | The created Shopify order | That an uncertain earlier request failed |
| Webhook delivery ID | A particular delivery for deduplication | A new commercial sale |
| Event ID | Related deliveries from the merchant action | That every related delivery requires a create action |
Shopify’s current delivery-verification documentation distinguishes X-Shopify-Webhook-Id for delivery deduplication from X-Shopify-Event-Id for correlation across subscriptions. It also describes verification before processing HTTPS payloads. Do not use the customer’s name or email to merge separate purchases.
Confirm the destination’s actual behaviour
The orderCreate reference defines a create operation and its inputs, permissions and errors. Check the API version or connector operation you use. Adding an external reference to a payload is not proof that repeat calls are automatically idempotent.
Design durable tracking of source references and outcomes around the actual supported operation. Concurrent attempts need coordinated handling; a separate lookup followed by creation can still race. Do not claim a complete implementation from a flowchart that ignores those transactions.
When a request times out, the outcome may be unknown. Reconcile the original request and destination record before sending another create. Do not assume a missing response authorises manual re-entry or a fresh identifier.
Verify replay and exception cases
Use an authorised non-production test arrangement and representative permitted data. Record the actual expected destination outcome for each case:
- The same verified delivery is received again.
- Related deliveries arrive from more than one subscription.
- A create response is lost after the destination accepts the order.
- An import overlaps another ingestion route.
- Two workers process the same source reference concurrently.
- A real second purchase, renewal, edit or refund arrives.
The repeat case should not create another sale, while legitimate activity must not disappear because a key was too broad. Test the connector’s precise behaviour instead of assigning a universal 24-hour or 72-hour protection window.
Reconcile without hiding the history
Keep appropriately protected records of source, identifiers, request time, outcome and exception handling. Give uncertain writes and detected conflicts an owner. A reconciliation report can reveal missing or duplicate records; it does not by itself prevent another write.
If duplicates already exist, review payment, fulfillment, inventory and notification consequences before any correction. Preserve the audit trail and follow authorised procedures. Do not automatically delete a lookalike order or refund a transaction solely because two records share a customer’s details.