Legacy API migration guide

Move integrations using the seven routes below to their canonical replacements. These legacy routes were deprecated on 2 July 2026 at 11:34:37 UTC and are no longer included in the OpenAPI specification.

Announced sunset: 2 October 2026 at 23:59:59 UTC.

This date is the end of the three-month migration window. Migrate before then. Publishing this notice does not disable the routes: removal requires a separate release after usage checks. Current responses, authentication and rate limits remain unchanged.

Route replacements

Legacy route	Replacement
`GET /api/orders/by-id`	`GET /api/orders/{shopifyOrderId}/address-detail`
`POST /api/orders/ai-correct-address`	`POST /api/orders/{shopifyOrderId}/address-correction`
`GET /api/merchant/connectors`	`GET /api/connectors`
`GET /api/document/shipping-label`	`GET /api/documents/shipping-labels`
`GET /api/document/invoice`	`GET /api/documents/invoices`
`POST /api/document/invoice/link`	`POST /api/orders/{shopifyOrderId}/documents`
`POST /api/v1/picking-lists/add-order`	`POST /api/picking-lists/{id}/add-order`

Identifiers and payload changes

A Shopify order ID and an xConnector internal order ID identify the same order in different systems. Do not substitute one for the other. OrderDTO.orderId is the Shopify ID; OrderDTO.merchantOrderId is the internal ID.

Address detail and AI correction

For address detail, move the legacy orderId query parameter (already a Shopify ID) into {shopifyOrderId}. The response remains the address-detail JSON object.

For AI correction, move the body orderId (also a Shopify ID) into the path and omit it from the JSON body. Keep the correction fields, idempotency key and precondition hashes. An optional body orderId must equal the path ID; a mismatch returns 400. Hash conflicts remain 409. Existing permission and automation requirements still apply.

Connector list and document downloads

These three replacements only change the route. The connector list still returns a JSON array. For shipping labels, keep connectorId and trackingNumber query parameters. For invoice downloads, keep connectorId, serie and number query parameters; the download parameter is still spelled serie. Downloads return PDF content when available, or 204 with no body when empty.

Attach an invoice to an order

The legacy query orderId is an internal order ID. Use the corresponding Shopify ID in /api/orders/{shopifyOrderId}/documents and send JSON with Content-Type: application/json:

{"type":"invoice","connectorId":123,"series":"INV","number":"456"}

The old query fields move to the body; prefer series instead of serie. The legacy spelling is accepted, but conflicting values for both spellings return 400. Omit merchantOrderId; if supplied, it is only a cross-check against the internal ID and must match the order resolved from the path.

Legacy outcomes are 201 with no body for a new link, or 204 with no body for an existing link or an invoice not found in the billing system. The canonical endpoint returns 201 with {"status":"created"}, 200 with {"status":"already_linked"}, or 422 with errorCode: invoice_not_found, respectively.

The canonical endpoint resolves the order before contacting the billing system: a missing order returns 404 even when the invoice is also absent. The legacy endpoint checks the billing system first and can return 204 in that case. Unsupported invoice-link connector types return 400 on the canonical endpoint.

Add an order to a picking list

The legacy body orderId is an internal ID. It accepts a pickingListId or pickingListName; name resolution can create a list. The canonical route requires an existing list ID in the path and the Shopify order ID in JSON:

POST /api/picking-lists/{id}/add-order
Content-Type: application/json

{"shopifyOrderId":123456789}

Resolve or create the list first through the canonical picking-list API. Do not send merchantOrderId: a non-null value returns 400 with the migration instruction merchantOrderId is no longer accepted; send shopifyOrderId = OrderDTO.orderId.

Both routes return 200 on success and 409 when the order is already in the same list. The canonical endpoint also returns 409 when it belongs to a different list; the legacy route can move it. The canonical response exposes shopifyOrderId and merchantOrderId; its deprecated orderId response field still means the internal ID. Consume shopifyOrderId for external order identity.

Recognizing the notice

Only the seven legacy aliases emit these headers, on success and error responses. The migration Link includes the application's context path when one is configured:

X-Deprecated: true
Deprecation: @1782992077
Sunset: Fri, 02 Oct 2026 23:59:59 GMT
Link: </api-migration.html>; rel="deprecation"; type="text/html"

Canonical routes are not deprecated. Use Authorization: Bearer <api-key> when migrating. Query-token compatibility is unchanged by this notice; its removal belongs to a separate authorization change and is not assigned this alias sunset date.