Skip to main content

​
Order Merge Pro API overview

​
Endpoints

GET /health returns HTTP 200 with status: "ok" when every required binding and public variable is present, or HTTP 503 with status: "degraded" otherwise. It does not expose secret values, and there is no /healthz route. The authenticated legacy routes /jobs and /jobs/:id redirect (302, and 307 for POST /jobs/:id) to their /app/jobs equivalents while preserving the query string.

​
Create a merge job

POST /api/merge creates a new merge job and starts the Durable Object state machine. The body is application/x-www-form-urlencoded (FormData): The authenticated session is the authoritative tenant; client-supplied shop values cannot select another shop. Responses:
  • 202 Accepted — job created, { "jobId", "status": "PENDING", "message" }. An idempotent request for an existing active job also returns 202 with "Merge job already in progress".
  • 200 OK — deduplicated terminal job already exists.
  • 409 Conflict — one or more orders are already part of an active merge job; the body lists conflictingJobs.
  • 400 Bad Request — validation error.
The idempotency key is {shop}:{primaryOrderId}:{sortedSecondaryIds joined by comma}. POST /api/merge is called by the embedded admin UI and only accepts requests carrying a valid Shopify embedded-admin session; it cannot be called directly with curl. To create merge jobs from an external system, use the public merge API below.

​
Public merge API

POST /api/public/merge is the Pro-only endpoint for creating merge jobs from external systems. Authenticate with an API key in the Authorization: Bearer <key> header or the X-OrderMerge-Api-Key header. Generate the key in the app under Integrations › API keys. The body is application/json: Responses:
  • 200 OK — a terminal merge job with the same idempotency key already exists (deduplicated).
  • 202 Accepted — job created successfully (same shape as /api/merge).
  • 400 Bad Request — invalid JSON body or malformed request schema.
  • 401 Unauthorized — missing or invalid API key.
  • 402 Payment Required — shop is not on Pro.
  • 409 Conflict — one or more orders are already part of an active merge job.
  • 503 Service Unavailable — no offline Shopify session exists for the shop.

​
Job status values

​
Outbound webhooks

Pro merchants can subscribe to merge.completed and merge.failed events. To register an endpoint, open Integrations › Webhooks in the app, enter the Endpoint URL, select the events, and choose Add subscription. The app then shows the webhook signing secret once; copy it before you dismiss the banner. Each subscription receives a signed POST to the registered URL. Subscription endpoints must use HTTPS and a public destination; registration and delivery reject loopback, private, link-local, reserved, and documentation IP literals (IPv4 and IPv6), single-label hosts, and local or internal DNS suffixes. Delivery uses manual redirect handling, so a 3xx response is reported as a failed delivery and is not followed. Delivery headers: Payload:
See Outbound webhooks and Shopify topics for the inbound Shopify topics the app handles. Pcnaid Documentation › Shopify Ecosystem › Order Merge Pro › Developer