Skip to main content

Import Provider Fulfillment Orphan

POST 
/api/sales-orders/:salesOrder/provider-fulfillment-snapshots/import

Create the SKU fulfillment entities for an orphan shipping-provider order with no counterpart (link_state orphan_importable) (Phase 3). When the provider order is not yet shipped (suggested_action import_fo) a FulfillmentOrder is created; when it is already shipped (suggested_action import_fo_and_sof) a FulfillmentOrder plus a SalesOrderFulfillment ship event with tracking is created. Provider item SKUs are matched against the sales order's unfulfilled lines.

Required scope: orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Import also resolves an orphan_duplicate (its products already fulfilled by an FO that has an active provider order). If the duplicate is still live at the carrier (suggested_action void_and_import) it is first voided there; then — or if it was already cancelled (suggested_action import_voided_fo) — it is recorded as a terminal voided "mirror" FulfillmentOrder linked to it, reserving no stock, so SKU mirrors the carrier 1:1.

Returns the refreshed reconciliation bundle (snapshots, orphans, summary) plus a message; the imported record now appears under snapshots[] attached to the new 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 the provider items cannot be matched to unfulfilled sales order lines, the order is already linked, the order belongs to a different sales order, or the orphan can no longer be found.

Orphans flagged marked_shipped_without_label (shipped at the provider with no label purchased and no tracking) are imported as a terminal voided mirror fulfillment order (external_type: provider_reconciliation_void_mirror) with no carrier call, no shipment, and no inventory impact — message: "Recorded the {Provider} order (marked shipped, no label purchased) as voided fulfillment order #N on {order}."

Tracking-match handling: a shipped orphan sharing a tracking number with a shipment already recorded on the order is never live-imported. If that shipment has no active provider order, the orphan is linked to it (response message: "Linked ... (same tracking)"); if the shipment is already provider-backed, the orphan is recorded as a voided mirror FO. A hand-typed "Mark as Shipped" tracking (payload externallyFulfilled=true) only counts as covered when it matches a recorded shipment — a unique typed tracking stays a live import.

Request​

Responses​

OK

Response Headers
    Content-Type