Future roadmap¶

This page summarizes the ingest API contract surfaces that are planned but not yet live in v1, with version targets and ADR pointers. Use it to plan integrations against the known horizon: what to design for, what to defer, what schema you can populate today even though the runtime won’t read it until later.

The contract guarantee: fields shipped in v1 schema stay backward-compatible. If a v1 caller populates a field that activates in v1.4, the v1.4 cutover does not require the upstream to change behavior — the data already lives in FG.AI.

Version horizon¶

Version	Anchor ADR(s)	Major capability adds	Status
v1 (launch)	many	3PL multi-tenant; lot/hazmat/temperature schema; drop-ship schema; the full document vocabulary; segregated consignor mode	active — what this contract documents
v1.1	ADR-0021	EDI 856 (ASN inbound) + EDI 855 (PO acknowledgment inbound); drop-ship gets EDI vendor signals	planned
v1.4	ADR-0029, ADR-0031, ADR-0034	`flow-service` ships: Stock Rules + Routes + Procurement Pull; activates drop-ship PO generation; activates hazmat / temperature Rule conditions	planned
v1.5	ADR-0030	Returns flow: `CustomerReturn` (RMA) + `VendorReturn` (RTV) document types; drop-ship returns	planned
v1.6	ADR-0032, ADR-0033	Carrier integration (`carrier-service`); lot tracking behavior activates (FEFO picking via Rule); cold-chain monitoring read-side	planned
v1.7	ADR-0037	Finance / ERP integration (`finance-service`): per-consignor billing, ERP posting	planned
v1.8	ADR-0041, ADR-0043	Advanced 3PL: commingled inventory mode, cross-consignor advanced analytics, consignment + VMI ownership semantics	planned
v2	ADR-0033	Serial tracking behavior activates; per-unit identifiers on movements	planned

v1.1 — EDI inbound¶

WMS ADR-0021 commits to EDI 856 (Advance Ship Notice) and EDI 855 (PO Acknowledgement) inbound translation. The translator emits the same Receiver and PO event shapes the ingest API uses today — your integration to the FG.AI side of the seam does not change. What changes is that vendors who only speak EDI can integrate without your upstream having to translate them first.

From the ingest API’s perspective: v1.1 is invisible to callers. Vendor tracking numbers and PO acknowledgements that arrive via EDI surface in the same sales_order_line.vendor_tracking_number field and same PO state-change webhooks you already consume.

v1.4 — `flow-service` (Stock Rules + Routes + Procurement)¶

WMS ADR-0029 introduces a new flow-service that owns:

Inbound Routes — what to do when goods land at the receiving dock (immediate putaway, quarantine, quality hold, cross-dock).
Putaway Strategies — where to put goods within the warehouse (closest empty bin, ABC-class slotting, hazmat-aware, temperature-aware).
Outbound Routes — wave release, waveless, batch picking, single-order picking, zone picking.
Procurement Pull Rules — when to generate a PO automatically (min-stock replenishment, drop-ship, MTO).

Most v1.4 ingest impact is behavioral, not schema-level. The schema needed to support these Rules already ships in v1. v1.4 activates:

Drop-ship PO generation (per Drop-ship)
Hazmat / temperature Rule conditions (per Hazmat and temperature)
Default cross-dock Routes when SO line and incoming Receiver line match
Procurement Pull for replenishment

Callers do not need to change their integration for v1.4. They may choose to: (a) configure Rules in the wms-admin UI; (b) stop manually generating drop-ship POs because the Pull rule will do it.

v1.5 — Returns flow¶

WMS ADR-0030 adds two new document types in v1.5:

New endpoint (v1.5)	Document type
`POST /wms-ingest/v1/documents/customer-returns`	CustomerReturn — RMA (Return Merchandise Authorization)
`POST /wms-ingest/v1/documents/vendor-returns`	VendorReturn — RTV (Return to Vendor)

The v1 schema reserves the document tables and accepts the linkage on RefurbishOrder.linked_customer_return_ref (see Extended document types), so v1 callers can structure their integration to be v1.5-ready.

Drop-ship returns ship in this version, completing the drop-ship picture.

v1.6 — Carrier service + lot behavior activates¶

Two parallel tracks in v1.6:

Carrier service (WMS ADR-0032) — outbound carrier dispatch, label generation, manifest creation. v1.6 default uses a 3rd-party multi-carrier platform (EasyPost / Shippo / ShipStation); direct carrier APIs deferred.
Lot tracking activates (WMS ADR-0033) — FEFO picking via Rule, lot genealogy queries, recall correlation. Schema already in v1; behavior turns on at v1.6.

The v1 schema’s vendor_tracking_number field plus inbound EDI 856 (v1.1) plus v1.6 carrier outbound integration close the round-trip on outbound tracking.

v1.7 — Finance / ERP integration¶

WMS ADR-0037 adds a finance-service that handles:

Per-consignor invoice generation (storage + transactional fees per consignor.billing_config)
ERP posting to QuickBooks Online / NetSuite / Xero (Phase 15 adapters)
3PL → consignor billing relationship; consignor → end-customer billing relationship

The v1 consignor.billing_config schema (see Consignor and 3PL) already captures the inputs finance-service will consume. Callers do not need to touch their consignor master-data integration when v1.7 ships.

v1.8 — Advanced 3PL features¶

WMS ADR-0041 (architecture) and ADR-0043 (consignment / VMI) ship advanced 3PL features in Phase 17 v1.8:

Commingled inventory mode — FIFO allocation across consignor ownership within a single bin. Non-trivial accounting + race conditions; deferred to give the v1 segregated mode time to harden.
Mixed-mode — per-SKU commingling policy in PSpec.
Cross-consignor advanced analytics — profitability + cost-to-serve, SLA scoring.
Sophisticated consignor-portal features — custom report builder, SLA dashboards.
Cross-consignor inventory transfers — ownership change between consignors at the same warehouse (rare; complex accounting).

v1 schema includes ownership fields (consignment_owner_id, vmi_mode) as nullable columns on inventory_record so v1.8 activation does not require migration.

v2 — Serial tracking¶

WMS ADR-0033 places serial-unit tracking in v2. The v1 schema reserves serial_unit table and nullable serial_no columns on inventory_record + movement_log. v2 activates per-unit cardinality.

What is not on the roadmap¶

The following were considered and explicitly excluded — there is no planned ingest API surface for them:

A customer-CX product. Per WMS ADR-0036, FG.AI exposes headless APIs + ecommerce-platform adapters; FG.AI does not build a customer-facing CX product.
A supply-chain visibility product. Per WMS ADR-0040, FG.AI exposes SCV primitives via this ingest API and webhooks; specialized SCV products integrate against them.
A compliance product. Per WMS ADR-0038, compliance is primitives (audit trail, lot genealogy, hazmat schema) consumed by per-industry compliance products.

What stays stable¶

The contract surface guarantees from v1:

URL paths under /wms-ingest/v1/ stay backward-compatible through all v1.x.
All v1 fields stay readable; new fields are optional and additive.
All v1 webhook event shapes stay compatible; new event kinds are gated behind subscription opt-in.
The semver promise is enforced by an OpenAPI breaking-change CI gate on the wms repo.

If a future version needs to break the contract, it ships as /wms-ingest/v2/ and v1 lives in parallel for the full deprecation window (minimum 18 months).