> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Sync OMS, Warehouse WMS, and Freight TMS

> Map order, inventory, and transportation ownership; import source orders; plan Freight loads; and recover original cross-system handoffs.

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.

| System | Owns | Does not establish on its own |
| - | - | - |
| Sync OMS | Canonical commercial order, source lines, status, and revision | Physical stock or carrier movement |
| Warehouse WMS | Facility/bin/SKU/lot custody, reservations, pick/pack, physical handoff, transfers, and returns | Carrier acceptance, transport delivery, or refunds |
| Freight TMS | Load plan, procurement, carrier coordination, transport execution, delivery evidence, and freight finance | Warehouse stock movement or bank execution |

```mermaid theme={null}
flowchart LR
  OMS["Sync OMS: canonical order"] -->|"reviewed source import"| WMS["Warehouse WMS: physical work"]
  WMS -->|"explicit planned-load request"| TMS["Freight TMS: transport"]
  TMS -->|"canonical source verification"| OMS
  WMS -->|"opt-in conditional fulfillment"| Receiver["Companion OMS receiver"]
  Receiver --> OMS
```

## 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:

```json theme={null}
{
  "your-wms-tenant": {
    "oms": {
      "base_url": "https://oms.example.com",
      "tenant_id": "your-oms-tenant",
      "api_key": "replace-with-tenant-scoped-oms-secret"
    },
    "tms": {
      "base_url": "https://freight-api.example.com",
      "tenant_id": "your-freight-tenant",
      "bearer_token": "replace-with-tenant-scoped-operations-secret"
    }
  }
}
```

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](/stateset-warehouse/quickstart) and
[TMS quickstart](/stateset-freight/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.