Connect the three services around their authoritative records. Sync is the OMS; Warehouse
is the WMS; Freight is the TMS. Deploy and verify each service separately before enabling
native mutations.
Establish the mapping
Have an authenticated Sync tenant/order, a WMS facility with matching whole-each SKUs, and
a Freight tenant with the actual customer and transport facts. Tenant IDs may differ between
services; configure their mapping explicitly.
Warehouse reads WMS_NATIVE_INTEGRATIONS_JSON on the server:
Replace example origins with your deployments and store secrets in server configuration.
The Freight credential needs operations.write; an integration role alone cannot create
the planned load. Freight’s own upstream Sync connection is configured separately through
FREIGHT_INTEGRATIONS_JSON. Confirm that both adapters resolve the intended canonical order.
Demo WMS cannot make native external requests.
Import the commercial order
The WMS lists candidates with GET /v1/integrations/oms/orders?page=1, reading Sync through
x-stateset-api-key. Import through
POST /v1/warehouses/{warehouse}/imports/oms with a retained request ID, reviewed warehouse
version, oms_order_id, exact source_updated_at, and verified customer/destination/priority
details.
Only eligible pending/processing, clearly unfulfilled source orders become new forward work.
Source line IDs and whole-unit quantities must match; duplicate-SKU lines retain separate
reservation owners. The canonical Sync order does not supply a customer address, so the
operator must provide a verified destination. Unknown products fail import rather than
silently creating catalog data.
The native source identity is oms:{upstream-tenant}:{UUID}. One full-source import owns that
source across all facilities in the WMS tenant. Splitting a commercial order across facilities
needs an explicit upstream assignment contract.
Execute warehouse work and request transportation
Receive and put away real stock, allocate the order, confirm actual picks, and pack it.
Inspect GET /v1/warehouses/{warehouse}/orders/{order}/readiness before transport planning.
Submit POST /v1/warehouses/{warehouse}/orders/{order}/transport with
{request_id, expected_version, plan}.
The explicit Freight plan needs its real customer, reference, mode, equipment, commodity,
weight, miles, pickup/delivery stops and dates, and buy/sell amounts in integer USD cents.
WMS does not infer transport facts from inventory or an order number.
WMS verifies Freight’s /v1/access tenant and operations.write capability, then calls
POST /v1/sync/import with {order_id, load} and its retained remote idempotency key.
Freight fetches its own canonical source and returns a linked planned load. This acknowledges
planning; it does not prove warehouse dispatch, carrier acceptance, or delivery.
Source status can change between the two services’ reads. An ineligible returned canonical
snapshot leaves WMS transport acceptance uncertain and requires review of the planned load.
Do not infer that the remote load was absent merely because WMS did not certify completion.
Record physical handoff and conditional OMS fulfillment
Warehouse records actual carrier handoff through its physical command path. OMS fulfillment
writeback stays held by default. Enabling it requires deploying and qualifying the
Warehouse repository’s companion Sync receiver, including its schema, then adding
"shipment_writeback": "conditional_v1" to the WMS tenant’s oms connection.
The receiver exposes GET/POST /v1/tenants/{tenant}/warehouse-fulfillments. WMS checks its
exact tenant and stateset.wms-fulfillment.v1 contract with conditional_revision,
terminal_state_fence, durable_idempotency, and durable_rejections capabilities. OMS
credentials need orders:read and orders:write.
After a fully shipped eligible order, an operator submits
POST /v1/warehouses/{warehouse}/orders/{order}/oms-fulfillment with
{request_id, expected_version}. The retained physical event, original source revision,
exact line quantities, recipient, and remote request identity stay fixed through recovery.
The receiver checks revision/state/lines atomically and records an accepted or durable
rejected receipt.
The current receiver is a whole-order, single-event protocol. Partial orders or multiple
physical handoffs remain held; WMS never invents a combined carrier/event. The adapter does
not fall back to the legacy unconditional fulfillment endpoint.
Recover the original handoff
Retain the WMS facility, actor, request body, and request ID. Read
GET /v1/warehouses/{warehouse}/native-requests/{request_id} to inspect original evidence
and attempts. Native transport states include frozen, sending, uncertain, and
completed; a local import may also have local_conflict.
An uncertain remote result must retain its original payload, key, recipient origin, tenant,
and reviewed source. Do not start another transport request for the same order or update
the body to today’s source revision. Credential rotation can retain the same authority;
changing destination or tenant holds the old intent. A validated durable rejection supplies
non-application evidence for that exact attempt; generic conflicts and timeouts do not.
Generic WMS webhooks have a separate producer contract and require compatible consumers.
Do not post them to Freight’s normalized EDI /v1/events route. Facility transfers retain
their own source/destination custody and do not create native order fulfillment or Freight
plans automatically.
Verify before live work
Check the actual service identity, capabilities, source lines, tenant mappings, and warehouse
reconciliation. Then qualify the deployed receiver, original-request recovery, and real
physical observations against the selected release. Source-derived fixtures and local
restore tests do not establish live carrier behavior or facility acceptance.
This guide was checked October 20, 2026 against stateset-warehouse/docs/native-integrations.md,
its companion receiver contract, and stateset-freight/docs/integrations.md and docs/api.md.
Start each service with the WMS quickstart and
TMS quickstart. Last modified on October 20, 2026
