API docs by Redocly

FG.AI WMS Ingestion API (1.0.0)

Download OpenAPI specification:

FG.AI Platform — WMS Ingest Maintainers: platform@flexgalaxy.ai URL: https://github.com/SiriusVoyager/wms License: Apache-2.0

Public REST surface for pushing master data, documents, and inventory into FG.AI WMS so the FG.AI planner can take over.

Overview

This is the public ingest contract for FG.AI WMS. Any upstream system — a third-party WMS, ERP, OMS, in-house legacy stack, or a FlexSync per-vendor connector — uses this contract to push master data, documents, and inventory into FG.AI WMS so that the FG.AI planner can take over.

It is the contract published by SiriusVoyager/wms and consumed by:

  • FlexSync per-vendor connectors (SiriusVoyager/flexsync — one connector per third-party WMS vendor: NetSuite, Manhattan, Blue Yonder, Körber, in-house legacy, etc.)
  • Third-party WMS / ERP / OMS that prefer to call FG.AI's API directly without going through FlexSync
  • System-integrator bridges between a customer's existing system of entry and FG.AI

Authoritative ADRs:

  • WMS ADR-0024 — FlexSync normalization layer relationship
  • WMS ADR-0022 — wes-contract, the alternative integration topology
  • WMS ADR-0025 — document-service split into business chains
  • WMS ADR-0008 — generic MES document vocabulary

Full developer documentation: https://docs.flexgalaxy.ai/dev/wms/.

What this is NOT

This is not the WMS↔WES contract. If a third-party WMS wants to keep its own planner and have FG.AI WES execute downstream, see wes-contract. The two contracts are mutually exclusive per warehouse — pick one.

Three entity classes

Class Endpoints Cadence
Master data /master/* Slow-changing. Sync at onboarding, then on every change.
Documents /documents/* Per-event. Push as the upstream creates / updates.
Inventory /inventory/* Snapshot at cutover; deltas during overlap; quiet after FG.AI is authoritative.

Once FG.AI has accepted the data, FG.AI's planner runs against it: wave / waveless release, slotting, cartonization, dispatch to FG.AI WES. The upstream is no longer in the planning loop.

Identity model

Every entity carries a partner-supplied source_id — the upstream's natural key. On first acceptance FG.AI assigns a stable internal_id and returns it. Subsequent upserts with the same (partner_id, source_id) mutate the same FG.AI entity.

Items may carry a monotonically-increasing source_version. If FG.AI already holds a higher version for the same (partner_id, source_id), the incoming upsert is ignored and reported as REPLAY. This makes out-of-order delivery safe.

Sync modes

Every upsert endpoint accepts a mode query parameter:

  • upsert (default) — steady-state. Create or update each item.
  • bulk — onboarding-scale loads. Returns 202 Accepted immediately with a job_id; caller polls /jobs/{job_id}.
  • full-refresh — destructive. Items not in the payload are tombstoned to INACTIVE. Use only for restoring known-good state.

Per-item outcomes

Each item in a batch lands in one of four states:

Status Meaning
ACCEPTED Normalized; internal_id returned.
REPLAY Same (partner_id, source_id, source_version) already accepted.
QUARANTINED Schema valid; business validation failed. Held in queue.
REJECTED Item-level schema invalid.

Quarantine is per-item, never per-batch. A batch of 1,000 SKUs with 3 bad UoM references returns 997 ACCEPTED + 3 QUARANTINED. Resolution paths are described in the developer docs.

Authentication

Direction Environment Scheme
Caller → FG.AI WMS Production mTLS
Caller → FG.AI WMS Dev / test API key (Bearer)
FG.AI WMS → caller (webhook) All HMAC-SHA256 over body, X-FGAI-Signature header

Warehouse and tenant scoping is enforced by the partner registry: a credential for WH-Tokyo-01 cannot push into WH-Tokyo-02; a credential for ACME-TENANT-A cannot push under ACME-TENANT-B.

Idempotency and ordering

  • Request-level: (partner_id, correlation_id) is the idempotency key. Retries return the original cached response with no reprocessing. 30-day retention.
  • Item-level: (partner_id, source_id) is the upsert key; combined with source_version it makes out-of-order delivery safe.
  • Webhook redelivery: at-least-once with exponential backoff. Recipients must be idempotent on (planner_id, correlation_id).

Versioning

Semver. Major version is in the URL (/wms-ingest/v1/); breaking changes introduce /wms-ingest/v2/. Minor versions add fields (always optional); patch versions are bug-fixes or clarifications only. Consumers pin to a specific minor (e.g. wms-ingest-client:1.0.0) and upgrade deliberately.

master

Master-data upsert — UoMs, SKUs, BOMs, Locations, Addresses, Lots, Serials. Slow-changing. Sync at onboarding, then on every change.

Upsert units of measure

Upsert one or more units of measure. UoMs are the dependency root of master data — register them before SKUs, BOMs, and any quantity-bearing entity.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Uom)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert SKUs

Upsert one or more SKUs. SKUs reference UoMs; a SKU upsert with an unregistered base_uom is QUARANTINED.

Lot- and serial-tracking flags on the SKU drive whether downstream movements require lot or serial fields. See WMS ADR-0033.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Sku)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "0193e4e3-1c8a-7c64-9b39-9d8c43c4a1b9",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert bills of materials

Upsert one or more BOMs. A BOM references a parent SKU and a list of component SKUs with quantities. All referenced SKUs must already exist or the upsert is QUARANTINED.

Used for assembled / kitted / refurbished products. See WMS ADR-0042.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Bom)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert locations (warehouse / zone / bin)

Upsert one or more locations. Locations form a hierarchy: WAREHOUSE → ZONE → BIN. A child location with an unregistered parent_source_id is QUARANTINED.

Onboarding order: warehouses first, then zones, then bins.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Location)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert addresses

Upsert postal addresses for warehouses, customers, suppliers, and carriers. Addresses are referenced from documents.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Address)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert lots

Register lots for lot-tracked SKUs. A movement against a lot-tracked SKU with an unregistered lot is rejected (422).

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Lot)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert serials

Register serial numbers for serial-tracked SKUs. A movement against a serial-tracked SKU with an unregistered serial is rejected (422).

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Serial)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

documents

Document upsert and cancellation — PurchaseOrders, SalesOrders, Receivers, Shippers, WorkOrders, TransferOrders. Per-event cadence; push as the upstream creates / updates them.

Upsert purchase orders

Upsert PurchaseOrder documents. Lines reference SKUs and UoMs from master data.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (PurchaseOrder)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert sales orders

Upsert SalesOrder documents.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (SalesOrder)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert receivers

Upsert Receiver documents — expected inbound from a PO or ASN. References a parent PO via po_source_id.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Receiver)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert shippers

Upsert Shipper documents — outbound shipment plans.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (Shipper)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert work orders

Upsert WorkOrder documents — production, assembly, refurbish. Production work orders reference a BOM for inputs and outputs.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (WorkOrder)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Upsert transfer orders

Upsert TransferOrder documents — inter-warehouse movement. See WMS ADR-0006 for the cross-warehouse saga model the FG.AI planner uses.

Authorizations:
mTLSApiKey
query Parameters
mode
string
Default: "upsert"
Enum: "upsert" "bulk" "full-refresh"

Sync mode.

  • upsert (default) — steady-state per-item create/update.
  • bulk — async; returns 202 with job_id.
  • full-refresh — destructive; tombstones items not in the payload to INACTIVE. Use only for restoring known-good state.
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (TransferOrder)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": true
}

Cancel a document

Soft-cancel a document — moves it to CANCELLED state. The document remains queryable for audit. Hard deletion is not supported.

type is required because the same source_id may exist across document types.

Authorizations:
mTLSApiKey
path Parameters
source_id
required
string (SourceId) [ 1 .. 256 ] characters
Example: SKU-WIDGET-RED-LG

Upstream's natural key for the entity. Treated as opaque. Cannot change once registered.

query Parameters
type
required
string (DocumentType)
Enum: "PR" "PO" "SO" "RECEIVER" "SHIPPER" "WORKORDER" "TRANSFER_ORDER" "VASORDER" "REFURBISH_ORDER"

Document type, matching WMS ADR-0008 generic MES vocabulary.

partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$
Example: partner_id=ACME-TENANT-A

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

reason
string <= 512 characters

Optional free-text cancellation reason.

Responses

Response samples

Content type
application/json
{
  • "source_id": "SKU-WIDGET-RED-LG",
  • "type": "PR",
  • "state": "DRAFT",
  • "cancelled_at": "2019-08-24T14:15:22Z"
}

inventory

Inventory snapshot and delta movements. Snapshot at cutover; deltas during overlap; quiet after FG.AI is authoritative.

Submit a full or partial inventory snapshot

Submit a point-in-time inventory snapshot.

  • scope=FULL — every (warehouse, sku, location, lot?, serial?) position on hand at as_of. Replaces FG.AI's view of the warehouse. Used at onboarding cutover and periodic reconciliation.
  • scope=PARTIAL — a scoped subset (zone, SKU class). Used to verify a subset without replacing the whole ledger.

After cutover, FG.AI WMS is authoritative for inventory and the upstream stops pushing snapshots.

Authorizations:
mTLSApiKey
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

scope
required
string
Enum: "FULL" "PARTIAL"
warehouse_source_id
required
string (SourceId) [ 1 .. 256 ] characters

Upstream's natural key for the entity. Treated as opaque. Cannot change once registered.

as_of
required
string <date-time> (Timestamp)

RFC 3339 timestamp with timezone offset (UTC Z recommended).

object or null

When scope=PARTIAL, the subset filter.

required
Array of objects (InventoryPosition)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "scope": "FULL",
  • "warehouse_source_id": "SKU-WIDGET-RED-LG",
  • "as_of": "2019-08-24T14:15:22Z",
  • "partial_scope": {
    },
  • "positions": [
    ]
}

Response samples

Content type
application/json
{
  • "snapshot_id": "string",
  • "replay": false,
  • "summary": {
    }
}

Submit inventory delta movements

Submit one or more inventory delta movements. Used during the overlap period between snapshot cutover and FG.AI becoming authoritative for inventory.

Movement kinds match the wes-contract movement kinds: PICK, PUT, MOVE, ADJUST, CONSUME, PRODUCE, RECEIVE, SHIP.

Once FG.AI is authoritative, the upstream should stop using this endpoint; inventory deltas thereafter flow through FG.AI WES → FG.AI WMS internally, not through this contract.

Authorizations:
mTLSApiKey
Request Body schema: application/json
required
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

object

Free-form metadata. Stored alongside the request. Not interpreted by FG.AI. Use for caller-side tracing, integration-instance markers, or batch source tags.

required
Array of objects (InventoryMovement)

Responses

Request samples

Content type
application/json
{
  • "partner_id": "ACME-TENANT-A",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "meta": { },
  • "movements": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "summary": {
    },
  • "replay": false
}

jobs

Async bulk job status and error pagination. Submitted via ?mode=bulk; polled via /jobs/{job_id}.

Get bulk job status

Returns the current state of a bulk upsert job. Submitted via ?mode=bulk on any upsert endpoint.

Job records are retained for 7 days after completion. Errors for completed-with-errors jobs are paginated at /jobs/{job_id}/errors and retained for 30 days.

Authorizations:
mTLSApiKey
path Parameters
job_id
required
string

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "state": "PENDING",
  • "counts": {
    },
  • "started_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "errors_url": "../dictionary"
}

Page through bulk job errors

Returns paginated per-item errors for a job that completed with errors (state: COMPLETED_WITH_ERRORS).

Authorizations:
mTLSApiKey
path Parameters
job_id
required
string
query Parameters
page_token
string

Opaque pagination token from a prior response.

page_size
integer [ 1 .. 1000 ]
Default: 100

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_page_token": "string",
  • "has_more": true
}

mappings

Look up FG.AI's internal_id for a (partner_id, source_id) pair. Useful for support and cross-system reconciliation.

Look up internal_id by source_id

Returns FG.AI's internal_id for a (partner_id, entity, source_id). Useful for support diagnostics and cross-system reconciliation.

Most integrations operate purely on source_id and never need this endpoint.

Authorizations:
mTLSApiKey
query Parameters
partner_id
required
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$
Example: partner_id=ACME-TENANT-A

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

entity
required
string
Enum: "uom" "sku" "bom" "location" "address" "lot" "serial" "purchase_order" "sales_order" "receiver" "shipper" "work_order" "transfer_order"
source_id
required
string (SourceId) [ 1 .. 256 ] characters
Example: source_id=SKU-WIDGET-RED-LG

Upstream's natural key for the entity. Treated as opaque. Cannot change once registered.

Responses

Response samples

Content type
application/json
{
  • "entity": "string",
  • "source_id": "SKU-WIDGET-RED-LG",
  • "internal_id": "fgai-sku-01HXABC...",
  • "partner_id": "ACME-TENANT-A",
  • "first_seen_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "lifecycle": "ACTIVE"
}

quarantine

List, inspect, and operator-release quarantined items. Most quarantines are resolved by fixing the underlying upstream data and re-upserting; operator release is the escape hatch.

List quarantined items

Paginated list of quarantined items, filterable by entity kind, state, time range, and partner. Backs the supervisor triage UI on integrator side.

Quarantine records expire 30 days after creation. Expired records require a fresh upsert from the upstream.

Authorizations:
mTLSApiKey
query Parameters
partner_id
string (PartnerId) ^[A-Za-z0-9._-]+-TENANT-[A-Za-z0-9._-]+$
Example: partner_id=ACME-TENANT-A

Composite partner identifier: {source-system-code}-TENANT-{tenant-code}. One partner_id per upstream tenant. FG.AI's partner registry scopes credentials to allowed warehouses and tenants.

entity_kind
string
Enum: "uom" "sku" "bom" "location" "address" "lot" "serial" "purchase_order" "sales_order" "receiver" "shipper" "work_order" "transfer_order" "inventory_position" "inventory_movement"
state
string
Enum: "PENDING" "RESOLVED_BY_RESUBMIT" "RESOLVED_BY_RELEASE" "EXPIRED"
since
string <date-time>
page_token
string
page_size
integer [ 1 .. 1000 ]
Default: 100

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_page_token": "string",
  • "has_more": true
}

Operator-release a quarantined item

Release a quarantined item into the canonical store as-is, suppressing the failed business validation. Use sparingly: it papers over real data-quality issues and the bad reference will still exist.

Releases are audited with operator identity and the required reason body field. Emits wms.quarantine.released-by-operator.

The right answer is almost always fixing the upstream data and re-upserting, not releasing.

Authorizations:
mTLSApiKey
path Parameters
quarantine_id
required
string
Request Body schema: application/json
required
reason
required
string [ 16 .. 2048 ] characters

Required substantive justification. Recorded in the audit log. "approved" or "fix" is not acceptable — describe the situation, the validation that was overridden, and the authorization source.

Responses

Request samples

Content type
application/json
{
  • "reason": "stringstringstri"
}

Response samples

Content type
application/json
{
  • "quarantine_id": "string",
  • "internal_id": "fgai-sku-01HXABC...",
  • "released_at": "2019-08-24T14:15:22Z"
}

introspection

Health, capabilities. Both for partner onboarding probes and operational dashboards.

Liveness and readiness probe

Returns service health. Used by operational dashboards and partner onboarding probes.

Responses

Response samples

Content type
application/json
{
  • "status": "UP",
  • "components": {
    }
}

Feature and version negotiation

Returns supported contract version, sync modes, thresholds, and webhook event kinds. Partners probe this during onboarding to discover server-side limits and feature flags.

Authorizations:
mTLSApiKey

Responses

Response samples

Content type
application/json
{
  • "contract_version": "1.0.0",
  • "supported_modes": [
    ],
  • "bulk_async_threshold": 0,
  • "webhook_events": [
    ],
  • "quarantine_retention_days": 30,
  • "job_record_retention_days": 7,
  • "job_error_retention_days": 30,
  • "idempotency_retention_days": 30
}

Document state changed (FG.AI → caller) Webhook

Emitted by FG.AI WMS when a document transitions between lifecycle states (RELEASED, PICKING, PICKED, PACKED, SHIPPED, RECEIVED, COMPLETED, CANCELLED, BLOCKED).

At-least-once with exponential-backoff retry. Receivers must be idempotent on (planner_id, correlation_id) and must verify the X-FGAI-Signature HMAC over the raw body.

Authorizations:
WebhookHmac
Request Body schema: application/json
required
event
required
string
Value: "document.state-changed"
correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

planner_id
required
string
occurred_at
required
string <date-time> (Timestamp)

RFC 3339 timestamp with timezone offset (UTC Z recommended).

required
object
from_state
required
string (DocumentState)
Enum: "DRAFT" "RELEASED" "PICKING" "PICKED" "PACKED" "SHIPPED" "RECEIVED" "IN_PROGRESS" "COMPLETED" "CANCELLED" "BLOCKED"

Document lifecycle state. Not all states apply to all document types — a Receiver has no PICKING state, for example.

to_state
required
string (DocumentState)
Enum: "DRAFT" "RELEASED" "PICKING" "PICKED" "PACKED" "SHIPPED" "RECEIVED" "IN_PROGRESS" "COMPLETED" "CANCELLED" "BLOCKED"

Document lifecycle state. Not all states apply to all document types — a Receiver has no PICKING state, for example.

object or null

Responses

Request samples

Content type
application/json
{
  • "event": "document.state-changed",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "planner_id": "fgai-wms",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "document_ref": {
    },
  • "from_state": "DRAFT",
  • "to_state": "DRAFT",
  • "actor": {
    }
}

Inventory adjusted (FG.AI → caller) Webhook

Emitted by FG.AI WMS when reconciliation produces an inventory adjustment vs the caller's prior baseline. Receivers may use this to mirror FG.AI's state back into their own system.

Authorizations:
WebhookHmac
Request Body schema: application/json
required
event
required
string
Value: "inventory.adjusted"
correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

planner_id
required
string
occurred_at
required
string <date-time> (Timestamp)

RFC 3339 timestamp with timezone offset (UTC Z recommended).

warehouse_id
required
string
sku
required
string
location
required
string
lot
string or null
serial
string or null
qty_delta
required
number (Quantity)

Numeric quantity. Precise; senders SHOULD send as a JSON number without exponent. Negative values are allowed only for ADJUST movements.

reason
required
string
Enum: "CYCLE_COUNT_RECONCILE" "DISCREPANCY_RESOLUTION" "DAMAGE" "SUPERVISOR_ADJUSTMENT" "OTHER"
object or null

Responses

Request samples

Content type
application/json
{
  • "event": "inventory.adjusted",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "planner_id": "fgai-wms",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "warehouse_id": "string",
  • "sku": "string",
  • "location": "string",
  • "lot": "string",
  • "serial": "string",
  • "qty_delta": 0,
  • "reason": "CYCLE_COUNT_RECONCILE",
  • "ref": {
    }
}

Item quarantined (FG.AI → caller) Webhook

Emitted by FG.AI WMS when an item is quarantined during normalization. Lets the caller's ops surface react without polling /quarantine.

Authorizations:
WebhookHmac
Request Body schema: application/json
required
event
required
string
Value: "master.normalization-conflict"
correlation_id
required
string <uuid> (CorrelationId)

Caller-generated UUID per request (UUID v4 or v7 recommended). Used as the request idempotency key (partner_id, correlation_id).

planner_id
required
string
occurred_at
required
string <date-time> (Timestamp)

RFC 3339 timestamp with timezone offset (UTC Z recommended).

entity_kind
required
string
source_id
required
string (SourceId) [ 1 .. 256 ] characters

Upstream's natural key for the entity. Treated as opaque. Cannot change once registered.

quarantine_id
required
string
reason
required
string
object

Responses

Request samples

Content type
application/json
{
  • "event": "master.normalization-conflict",
  • "correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
  • "planner_id": "fgai-wms",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "entity_kind": "string",
  • "source_id": "SKU-WIDGET-RED-LG",
  • "quarantine_id": "string",
  • "reason": "string",
  • "submitted_payload": { }
}