Skip to main content

Get Provider Fulfillment Snapshots

GET 
/api/sales-orders/:salesOrder/provider-fulfillment-snapshots

Read-only provider order/shipment visibility & reconciliation for the Sales Order Fulfillments tab.

Required scope: orders:read

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

Returns each connected shipping provider's cached order/shipment (Starshipit + ShipStation pilots), matched to this sales order by the {sales_order_number}.{fulfillment_sequence} reference, and classified into a reconciliation state:

  • matched — attached to an FO/SOF on this order and items agree
  • item_mismatch — attached, but provider items differ from our lines
  • orphan_linkable — unattached, but a matching FO/SOF exists (repair target)
  • orphan_importable — unattached and no matching FO/SOF (import candidate)
  • orphan_duplicate — unattached, but its products are already fulfilled by an FO that has an active provider order (a duplicate at the carrier; resolve by voiding it there and recording a voided FO)

snapshots[] are attached to an FO/SOF (see attached_to); orphans[] are unattached provider records; summary carries per-state counts.

Authentication: requires a Bearer token (Personal Access Token). Read-only — no query parameters. Cache-only (no live provider call); last_synced_at reflects staleness. Gated by the fulfillment.provider_snapshots_enabled flag — returns 404 when disabled so the UI degrades gracefully.

Each orphan carries a suggested_action: link, import_fo, import_fo_and_sof, void_and_import (live duplicate), or import_voided_fo (already-cancelled duplicate). summary includes per-state counts, including orphan_duplicate.

Each snapshot/orphan entry includes marked_shipped_without_label (boolean): true when the provider order reports shipped but no label was ever purchased and no tracking exists anywhere (the ShipStation "Mark as Shipped" fingerprint). Such orphans get suggested_action: import_voided_fo — importing records a terminal voided mirror fulfillment order instead of a live FO/SOF.

marked_shipped_without_label also covers hand-typed trackings: a "Mark as Shipped" order (ShipStation payload externallyFulfilled=true) with a typed tracking is flagged only when that tracking matches a shipment already recorded on the order. Shipped orphans sharing a tracking with a recorded shipment classify as orphan_linkable (free shipment) or orphan_duplicate with import_voided_fo (shipment already provider-backed).

Each attached snapshot may carry a discrepancy object when a shipping provider shipped a fulfillment order whose line SKU cannot fulfill from on-hand stock: { fulfillment_order_id, can_accept, accepted, discrepant_lines[], fulfillable_lines[] }. When can_accept is true, POST the fulfillment order's accept-discrepancy endpoint to ship the fulfillable lines and park the rest. Null when there is no discrepancy to surface.

Request​

Responses​

OK

Response Headers
    Content-Type