> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/fulfillment-api/resources/tutorials/synchronizing-inventory.md). # Synchronizing Inventory The inventory sync endpoint is how 3PL providers and retailers keep ESW's fulfilment system aligned with physical stock levels at a warehouse or fulfilment centre. ESW uses this data to determine which orders can be allocated, which SKUs are available for new orders, and which items should be withheld from fulfilment due to quality or compliance issues. Every item in the sync carries an `articleStatus` that tells ESW not just *how many* units are present, but *what state* those units are in. ```http POST /v1/Inventory/Sync Authorization: Bearer Content-Type: application/json ``` *** ### When to Call This Endpoint Call `POST /Inventory/Sync` when: * **Stock arrives at a fulfilment centre** — goods received from the retailer, sync all inbound SKUs as `Expected` transitioning to `Active` once quality-checked * **Inventory counts change** — daily or real-time quantity updates from your WMS * **SKU status changes** — an item moves from `Active` to `Quarantine` due to a quality issue, or from `Quarantine` back to `Active` after clearance * **New SKUs are added** — when a new product is received at the fulfilment centre for the first time * **Inventory is suspended** — when a line of goods must be withheld from fulfilment entirely *** ### Request Structure `InventorySyncRequest` has four required fields and no optional top-level fields. ```json POST /v1/Inventory/Sync { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "MyWarehouseName", "items": [ ... ] } ``` | Field | Type | Required | Constraints | Description | | --------------------- | ------ | -------- | ----------- | --------------------------------------------------------------------------------------- | | `tenantCode` | string | ✅ | Min 1 char | ESW's unique identifier for the retailer brand | | `fulfillmentCentreId` | string | ✅ | Min 1 char | The identifier for the specific warehouse or fulfilment centre where the stock is held | | `provider` | string | ✅ | — | The name of the 3PL provider or system submitting this sync. Used for audit and routing | | `items` | array | ✅ | Min 1 item | The SKUs to sync — see Steps 3–7 | *** ### `fulfillmentCentreId` and `provider` #### `fulfillmentCentreId` This is the identifier for the physical location where the stock is held. It must match the fulfilment centre identifier as configured in ESW's system — values are agreed during onboarding and cannot be arbitrary strings. ```json "fulfillmentCentreId": "FC-MILAN-01" ``` Common format examples (exact values are provided by ESW during integration setup): * `"FC-MILAN-01"` — Milan warehouse, unit 1 * `"FC-DUBLIN-MAIN"` — Dublin main distribution centre * `"WH-US-LOS-ANGELES"` — US west coast warehouse #### `provider` `provider` identifies which system or 3PL submitted the sync. It is used for audit trails and to differentiate syncs from multiple providers sharing the same fulfilment centre. ```json "provider": "Ingram Micro" ``` This is a free-text string with no validation constraint — use a value that meaningfully identifies your WMS or organization. Conventions vary by integration, but typically use the 3PL company name or WMS system name. *** ### `InventorySyncItem` Fields Each entry in `items` represents one SKU at the specified fulfilment centre. ```json { "sku": "SKU-00123", "articleStatus": "Active", "quantity": 45, "variantProductCode": "SKU-00123-TAN-OS", "upc": "012345678901", "ean": "5012345678906", "size": "One Size", "color": "Tan" } ``` #### Required fields per item | Field | Type | Constraints | Description | | --------------- | ------ | ------------------------- | ------------------------------------------ | | `sku` | string | Min 3 chars, max 32 chars | The retailer's primary SKU or product code | | `articleStatus` | enum | See Step 6 | The operational status of the stock | #### Optional fields per item | Field | Type | Constraints | Description | | -------------------- | ------- | ------------------------- | --------------------------------------------------------- | | `quantity` | integer | — | Current quantity in stock at this status. See Step 7. | | `variantProductCode` | string | Min 1 char, max 100 chars | The variant-level product code — more specific than `sku` | | `upc` | string | — | Universal Product Code (12-digit North American barcode) | | `ean` | string | — | European Article Number (13-digit international barcode) | | `size` | string | — | Product size — e.g. `"M"`, `"42"`, `"One Size"` | | `color` | string | — | Product colour — e.g. `"Tan"`, `"Navy"` | *** ### SKU Identification Fields ESW uses the `sku` as the primary identifier for inventory records. The additional identification fields (`variantProductCode`, `upc`, `ean`) provide supplementary lookup keys and help ESW match warehouse stock to order items precisely. #### `sku` — primary identifier The base SKU — your core product code. Must be between 3 and 32 characters. ```json "sku": "SKU-00123" ``` This is the same SKU used when the product was registered in ESW's catalog. Consistency is essential — a mismatch between the SKU in the catalog and the SKU in the inventory sync will result in ESW being unable to match the stock to order items. #### `variantProductCode` — variant-level specificity When a single `sku` covers multiple variants (sizes, colors), use `variantProductCode` to identify the specific variant. ```json "sku": "SKU-00456", "variantProductCode": "SKU-00456-BROWN-90CM" ``` Provide this when your products have variant-level differentiation that ESW needs to track separately — for example, a belt that comes in multiple sizes and colors where each variant has its own stock level. #### `upc` and `ean` — barcode identifiers These allow ESW to cross-reference inventory against order items using standard barcode formats. ```json "upc": "012345678901", "ean": "5012345678906" ``` Provide both when your warehouse management system scans barcodes rather than looking up SKUs directly. This is especially useful for returns processing where the item is identified by barcode. #### `size` and `color` — attribute descriptors Descriptive attributes that provide additional context alongside the SKU identifiers. These are informational rather than lookup keys. ```json "size": "90cm", "color": "Brown" ``` *** ### `ArticleStatus` — The Four Values `articleStatus` is the most operationally significant field on each item. It tells ESW what state the physical goods are in, which determines whether ESW will allocate those units to orders. #### `"Active"` — available for allocation ```json "articleStatus": "Active" ``` The stock is in good condition and available for ESW to allocate to shopper orders. This is the normal state for goods that have been received, quality-checked, and are ready to fulfil. **Operational effect:** ESW will draw down this stock when allocating orders for the corresponding SKU. **When to use:** After goods have passed goods-in inspection and are physically available in a pickable location in the warehouse. *** #### `"Expected"` — inbound, not yet received ```json "articleStatus": "Expected", "quantity": 200 ``` Stock that has been dispatched from the retailer but has not yet arrived at the fulfilment centre, or has arrived but not yet been booked in. ESW knows it is coming but will not allocate it to orders. **Operational effect:** ESW records the expected quantity for planning purposes but does not use it for order allocation. Once goods arrive and pass inspection, sync them again as `Active`. **When to use:** * When the retailer has dispatched an inbound shipment and wants ESW to anticipate the arrival * After a purchase order is confirmed but before physical delivery **Typical lifecycle:** ``` Supplier dispatches goods → sync as "Expected" ↓ Goods arrive at warehouse → sync as "Active" (once booked in) ``` *** #### `"Quarantine"` — present but withheld ```json "articleStatus": "Quarantine", "quantity": 15 ``` Stock is physically at the fulfilment centre but has been withheld from fulfilment. This is used when goods have failed quality inspection, are awaiting regulatory clearance, or have been flagged for investigation. **Operational effect:** ESW will not allocate quarantined stock to orders. The quantity is visible to ESW for reporting but is excluded from available inventory. **When to use:** * Goods received with quality defects — hold until inspected * Items subject to a recall or compliance investigation * Seasonal goods being held until a release date * Goods awaiting customs clearance documentation **Quarantine → Active transition:** Once the issue is resolved, sync the same SKU again with `articleStatus: "Active"` to make the stock allocatable. *** #### `"Suspended"` — permanently withdrawn ```json "articleStatus": "Suspended", "quantity": 0 ``` Stock has been permanently withdrawn from the ESW fulfilment programme. This is distinct from `Quarantine` — suspended goods are not expected to return to `Active` status. **Operational effect:** ESW removes the stock from its available inventory entirely. Any pending allocations for the SKU may be affected depending on your integration configuration. **When to use:** * A product line has been discontinued * A retailer has ended their relationship with a specific fulfilment centre and the goods are being repatriated * A SKU has been replaced by a new SKU and the old record should be decommissioned **Important:** Syncing `Suspended` with `quantity: 0` is the correct pattern for telling ESW that a SKU no longer exists at this fulfilment centre. #### Status transition rules | From | To | Allowed? | When | | ------------ | ------------ | -------- | ------------------------------------------ | | `Expected` | `Active` | ✅ | Goods received and booked in | | `Active` | `Quarantine` | ✅ | Quality issue detected | | `Quarantine` | `Active` | ✅ | Issue resolved | | `Active` | `Suspended` | ✅ | SKU discontinued | | `Quarantine` | `Suspended` | ✅ | Issue unresolvable — goods to be destroyed | | `Suspended` | `Active` | ⚠️ | Only with ESW agreement — unusual | *** ### The `quantity` Field `quantity` is optional, but its absence has a specific meaning — omitting it signals that you are updating the status of a SKU without reporting a quantity change. Include it when: * Reporting actual on-hand stock levels * Syncing `Expected` quantities from an inbound purchase order * Reporting zero stock (`quantity: 0`) to deactivate a SKU ```json { "sku": "SKU-00123", "articleStatus": "Active", "quantity": 45 } ``` #### Quantity represents the total at that status `quantity` is the total number of units of the SKU in the specified `articleStatus` at the fulfilment centre — not a delta. If you previously synced 50 units as `Active` and 10 were sold, sync `quantity: 40` (the current count), not `quantity: -10`. #### Zero quantity Syncing `quantity: 0` for an `Active` SKU tells ESW the item is out of stock at this location. New orders for that SKU will not be allocated to this fulfilment centre. ```json { "sku": "SKU-00789", "articleStatus": "Active", "quantity": 0 } ``` *** ### Single SKU vs Bulk Sync Patterns The `items` array supports any number of SKUs in a single request. Use the pattern that matches your warehouse system's capabilities. #### Single SKU — event-driven sync Call the endpoint each time a specific SKU's quantity or status changes. Suitable for real-time WMS integrations. {% code expandable="true" %} ```json { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-00123", "articleStatus": "Active", "quantity": 44 } ] } ``` {% endcode %} #### Bulk sync — full stock count Submit all SKUs at the fulfilment centre in a single call. Suitable for end-of-day or periodic full inventory reconciliation. {% code expandable="true" %} ```json { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-00123", "articleStatus": "Active", "quantity": 44 }, { "sku": "SKU-00456", "articleStatus": "Active", "quantity": 112 }, { "sku": "SKU-00789", "articleStatus": "Quarantine", "quantity": 8 }, { "sku": "SKU-00999", "articleStatus": "Expected", "quantity": 200 }, { "sku": "SKU-01001", "articleStatus": "Active", "quantity": 0 } ] } ``` {% endcode %} #### Mixed status bulk sync You can include the same SKU multiple times in one request with different statuses — for example, when part of a SKU's stock is `Active` and another portion is `Quarantine`. json {% code expandable="true" %} ```json "items": [ { "sku": "SKU-00789", "articleStatus": "Active", "quantity": 25 }, { "sku": "SKU-00789", "articleStatus": "Quarantine", "quantity": 8 } ] ``` {% endcode %} This tells ESW: 25 units of SKU-00789 are allocatable and 8 are quarantined at this fulfilment centre. *** ### Examples {% hint style="info" icon="arrow-progress" %} #### Example A — Goods received, booked in as Active {% endhint %} A shipment of wallets and belts has arrived and passed goods-in inspection. {% code expandable="true" %} ```json POST /v1/Inventory/Sync { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-00123", "variantProductCode": "SKU-00123-TAN-OS", "ean": "5012345678906", "color": "Tan", "size": "One Size", "articleStatus": "Active", "quantity": 150 }, { "sku": "SKU-00456", "variantProductCode": "SKU-00456-BROWN-90CM", "ean": "5012345678913", "color": "Brown", "size": "90cm", "articleStatus": "Active", "quantity": 85 } ] } ``` {% endcode %} *** {% hint style="info" icon="arrow-progress" %} #### Example B — Inbound shipment anticipated (Expected) {% endhint %} A purchase order has been dispatched from the supplier. Warehouse notifies ESW before physical arrival. {% code expandable="true" %} ```json POST /v1/Inventory/Sync { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-00789", "articleStatus": "Expected", "quantity": 300 } ] } ``` {% endcode %} Follow-up after goods arrive and pass inspection: ```json { "items": [ { "sku": "SKU-00789", "articleStatus": "Active", "quantity": 298 } ] } ``` (2 units short-delivered — quantity adjusted to actual count.) *** {% hint style="info" icon="arrow-progress" %} #### Example C — Quality issue detected, partial quarantine {% endhint %} A batch of scarves has arrived. 250 passed inspection; 18 have a defect and are quarantined pending disposal decision. {% code expandable="true" %} ```json POST /v1/Inventory/Sync { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-00789", "articleStatus": "Active", "quantity": 250 }, { "sku": "SKU-00789", "articleStatus": "Quarantine", "quantity": 18 } ] } ``` {% endcode %} *** {% hint style="info" icon="arrow-progress" %} #### Example D — SKU suspended at fulfilment centre {% endhint %} A product line has been discontinued. Remaining stock is being returned to the retailer. {% code expandable="true" %} ```json POST /v1/Inventory/Sync { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-01001", "articleStatus": "Suspended", "quantity": 0 } ] } ``` {% endcode %} *** {% hint style="info" icon="arrow-progress" %} #### Example E — End-of-day full reconciliation {% endhint %} Daily full stock count across all SKUs at the fulfilment centre. {% code expandable="true" %} ```json POST /v1/Inventory/Sync { "tenantCode": "MYBRAND", "fulfillmentCentreId": "FC-MILAN-01", "provider": "Ingram Micro", "items": [ { "sku": "SKU-00123", "articleStatus": "Active", "quantity": 143 }, { "sku": "SKU-00456", "articleStatus": "Active", "quantity": 79 }, { "sku": "SKU-00789", "articleStatus": "Active", "quantity": 250 }, { "sku": "SKU-00789", "articleStatus": "Quarantine", "quantity": 18 }, { "sku": "SKU-00999", "articleStatus": "Expected", "quantity": 200 }, { "sku": "SKU-01001", "articleStatus": "Suspended", "quantity": 0 } ] } ``` {% endcode %} *** ### Response and Error Handling #### Success — `202 Accepted` ```http HTTP/1.1 202 Accepted (empty body) ``` `202` means the request was received and queued for processing — not that inventory records have been updated yet. Processing is asynchronous. Allow a short delay before querying inventory state if verification is needed. #### `400 Bad Request` — `ValidationProblemDetails` {% code expandable="true" %} ```json { "errors": { "items[0].sku": [ "The sku field must be between 3 and 32 characters." ], "fulfillmentCentreId": [ "The fulfillmentCentreId field is required." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "detail": "See the errors property for details.", "instance": "/v1/Inventory/Sync" } ``` {% endcode %} The `errors` object is keyed by field path — each key maps to an array of error strings for that field. Multiple validation failures are returned together. Fix every error listed before resubmitting. #### Common validation errors | Field | Error | Fix | | ------------------------ | ---------------------------------- | ----------------------------------------------------------- | | `tenantCode` | Required | Include `tenantCode` | | `fulfillmentCentreId` | Required | Include `fulfillmentCentreId` | | `items[n].sku` | Too short (< 3) or too long (> 32) | Check SKU length constraints | | `items[n].articleStatus` | Invalid value | Use one of: `Expected`, `Active`, `Quarantine`, `Suspended` | | `items` | Required / empty | Include at least one item | *** ### Quick Reference ``` InventorySyncRequest ├── tenantCode ← brand identifier (required) ├── fulfillmentCentreId ← warehouse ID (required, ESW-configured) ├── provider ← 3PL or system name (required) └── items[] ├── sku ← 3–32 chars (required) ├── articleStatus ← Active | Expected | Quarantine | Suspended (required) ├── quantity ← total units at this status (optional but recommended) ├── variantProductCode ← variant-level SKU (optional) ├── upc ← 12-digit barcode (optional) ├── ean ← 13-digit barcode (optional) ├── size ← product size (optional) └── color ← product colour (optional) ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/fulfillment-api/resources/tutorials/synchronizing-inventory.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.