Order Merge Pro quickstart
What it is
Order Merge Pro is a production embedded Shopify Admin app that merges multiple orders into a single shipment. It is built on React Router 7 and Cloudflare Workers and uses Shopify’sorderEdit GraphQL workflow, a Durable Object state machine, and immutable audit logging. The app is embedded (embedded = true) and is declared as an orders and shipping app.
Where to start
- Architecture overview — runtime components, the 12-status state machine, and data flow.
- API overview — the externally reachable HTTP surface and job status values.
- Outbound webhooks and Shopify topics — the Shopify topics the app handles and the events it emits.
Shopify access scopes
The app declares these scopes inshopify.app.toml:
read_orders, write_orders, read_order_edits, write_order_edits, read_customers, read_companies, read_products, read_locations, read_inventory, write_inventory, read_fulfillments, write_fulfillments, read_assigned_fulfillment_orders, read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders, read_shipping, write_app_proxy, read_metaobjects, write_metaobjects, read_metaobject_definitions, write_metaobject_definitions.
The scopes support order discovery and edits, inventory and fulfillment validation, shipping refunds, the signed customer portal (write_app_proxy), and the app-owned merge-rule metafields and metaobjects.
Admin UI extensions
The app ships three UI extensions:
Extensions reach the app through the signed session token and the
/api/admin-merge-context and /api/embedded-navigation endpoints, which resolve safe Shopify-admin App Home links.
Integration entry points
- Public merge API — create merge jobs from an external system with a Pro API key at
POST /api/public/merge. - Outbound webhooks — subscribe to
merge.completedandmerge.failedevents. - Customer self-service portal — a signed Shopify app proxy at
/apps/order-merge-prothat the app serves from/portal/merge.