Repair Provider Fulfillment Orphan
POST/api/sales-orders/:salesOrder/provider-fulfillment-snapshots/repair
Link an orphan shipping-provider order (link_state orphan_linkable, suggested_action link) to an existing FulfillmentOrder / SalesOrderFulfillment already on this sales order whose lines cover the same products (Phase 2). Only links to an FO/SOF that does NOT already have an active (non-cancelled) provider order — two active provider orders on one FO is invalid. An orphan whose only match is already taken is classified orphan_duplicate (use Import) instead of orphan_linkable, and a repair attempt against it is rejected with 422. Use the provider, integration_instance_id, and external_order_id from the orphan returned by GET provider-fulfillment-snapshots.
orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Returns the refreshed reconciliation bundle (snapshots, orphans, summary) plus a message describing the link. The previously-orphaned record now appears under snapshots[] attached to its FO/SOF.
Request body:
provider(string, required) — the carrier that owns the order (e.g.starshipit).integration_instance_id(integer, optional) — the provider integration instance the order belongs to.external_order_id(string, required) — the carrier-side order id.
Authentication: Bearer token. Requires the sales_orders.fulfill permission.
Gated by the fulfillment.provider_snapshots_enabled flag — 404 when disabled.
Returns 422 when no matching FO/SOF exists to link to, the order is already linked, the order belongs to a different sales order, or the orphan can no longer be found.
A tracking-based fallback supplements the SKU-set shipment matcher: when the orphan's label/tracking matches a recorded fulfilled shipment that has no active provider order, the orphan links to that shipment even if their item sets differ (e.g. post-repair consolidated shipments).
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.