Skip to main content

​
Order Merge Pro architecture

​
Runtime

Order Merge Pro is an embedded Shopify Admin app built on React Router 7 running on Cloudflare Workers. A Durable Object drives an explicit merge state machine, D1 stores job state, KV holds OAuth sessions and rate-limit counters, R2 stores immutable audit logs and GDPR exports, and Cloudflare Queues handle Durable Object start retries and deferred business webhooks.

​
Merge state machine

A merge validates orders, stages and commits Shopify order edits, cancels secondary orders, and refunds redundant shipping. RECOVERY_REQUIRED is a bounded operator state, not a terminal failure: the job-detail POST can resume the recorded commit or cancellation state after store-owner authorization.
Key design decisions:

​
Product data flow

  1. Candidate discovery reads unfulfilled orders, groups them by customer, normalized shipping address, and currency, and filters with the shop’s entitlements.
  2. A merge stages line items onto the primary order edit, applies the paid-on-secondary discount and, on Basic and Pro, carries the secondary outstanding balance as a custom line, then verifies the staged total.
  3. The job verifies tracked on-hand inventory at each fulfillment location, commits the primary edit, then cancels the secondary orders.
  4. Cancellation confirmations arrive over the orders/updated webhook and are enqueued to the merge queue.
  5. The job refunds redundant secondary shipping, tags the orders, and completes.
Queue configuration allows an initial delivery plus three retries. Exhausted merge-retry messages reach a dead-letter queue; exhausted webhook work marks its D1 receipt FAILED and is acknowledged.

​
B2B approval flow

Only Shopify PurchasingCompany orders from one company can enter the B2B approval workflow. The server reloads every order instead of trusting dashboard form data. The account owner is derived from the online Shopify session; no merchant-entered shop or role value participates in authorization. A decision lease serializes concurrent approvals, and retrying after a lost lease is safe because merge-job creation uses the same deterministic order-set idempotency key. If merge creation fails, the request returns to PENDING with a merchant-visible error.

​
Idempotency

Merge operations use a deterministic key: {shop}:{primaryOrderId}:{sortedSecondaryIds joined by comma}. This prevents duplicate merges from double-clicks, race conditions from concurrent requests, and reprocessing of completed merges.

​
Security model

  • Admin routes authenticate with authenticate.admin().
  • Webhooks use SDK HMAC verification, with unchanged raw-body HMAC-before-parse for the compliance topics.
  • Job queries are scoped to the authenticated session shop.
  • Server-side plan guards gate every premium action, and the Free monthly merge limit is enforced before job creation.
  • The shop is derived from session.shop, the authenticated webhook shop, or signed app-proxy parameters, never merchant input.
  • Shopify access and refresh tokens in KV and merge-job access tokens in the Durable Object context use AES-256-GCM envelopes with a rotatable encryption key.
  • Audit metadata automatically redacts sensitive token, secret, password, and credential keys before the R2 write.

​
Error handling

Pre-commit and non-recoverable errors transition to FAILED. Ambiguous commit outcomes and exhausted post-commit cancellation recovery transition to RECOVERY_REQUIRED, where only the store owner can retry. The queue consumer retries up to the configured maximum, and Durable Object alarms reconcile commit and cancellation work at 5-minute intervals before manual recovery is required. See the quickstart for scopes and integration entry points, the API overview for documented interfaces, and the merchant setup guide for the store-facing workflow. Pcnaid Documentation › Shopify Ecosystem › Order Merge Pro › Developer