Inventory Batch API

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Fluent Commerce

Changed on:

9 Feb 2025

Overview

The Inventory Batch is designed to send large volumes of inventory data, primarily to update the Last On Hand inventory quantities for inventory positions. While its primary purpose is to handle large-scale inventory updates and ensure the OMS reflects the latest inventory levels after a few days of operations, it is flexible enough to support other inventory types as needed, providing adaptability for diverse inventory management scenarios.

Key points

Create new Inventory Batches using the Job API
Sample Inventory batch payload
Inventory batch details

Inventory Batch Submission

In order to create/update inventory data, one can submit an inventory batch using the

`/job/{jobId}/batch`

endpoint (see link). Multiple Inventory can be updated in a single batch by providing multiple

`entities`

Inventory Batch Model

The Inventory Batch Model consists of:

Batch-Level Fields: Define overall batch properties.
Entities Array: Contains individual inventory items to process.

Field	Type	Mandatory?	Possible Values	Default Value	Description	Notes
action	String	✅	"UPSERT"	N/A	Specifies the operation on inventory entities (e.g., "UPSERT" to insert/update).	Must be a valid action type for inventory operations.
entityType	String	✅	"INVENTORY"	N/A	Defines the type of entity being processed.	Must be "INVENTORY".
source	String	❌	Any valid source identifier	"batch"	Identifies the origin of the batch data (e.g., "ERP", "POS").	Defaults to "batch" if not provided.
event	String	❌	Any valid event name	"InventoryChanged"	Custom event name associated with the batch operation.	Defaults to "InventoryChanged" if not provided.
catalogueRef	String	❌	Any valid catalogue reference	"DEFAULT:<retailerId>"	References the catalogue associated with the inventory batch.	Influences `catalogueType` in `ref` construction.
conditions	Object	❌	Configuration object	Uses default transient settings	Configurations like transient types and statuses are used in de-duplication checks.
hasRelatedInventoryQuantities	Array	❌	List of transient IQ types and statuses	Default transient types and statuses	Defines custom transient types and statuses for checking during de-duplication.	Do note for performance reasons, any transient type with the status "INACTIVE" is ignored
entities	Array	✅	List of inventory items	N/A	List of inventory items	Follows the entities object model. Nonconforming inputs are ignored.

Each object within the

`entities`

array should follow this structure:

Field	Type	Mandatory?	Possible Values	Constraints	Description	Notes
locationRef	String	✅	Any valid location reference	N/A	The location reference used to match the inventory.
skuRef	String	✅	Any valid SKU reference	N/A	The SKU reference of the inventory item.
qty	Integer	✅	Any non-negative integer	N/A	The quantity to match the on-hand inventory.
correctedQty	Integer	❌	Any non-negative integer	Defaults to 0 if not provided	The current outstanding correction quantity to be saved.
type	String	❌	Any valid type identifier	N/A	Specifies the type of inventory operation (e.g., "LAST_ON_HAND").	Defaults to "LAST_ON_HAND" if not provided.
ref	String	❌	Any valid reference	Must follow `<skuRef>:<locationRef>:<catalogueType>:<type>`	A reference identifier for the inventory entity.	If not provided, constructed using `skuRef` , `locationRef` , `catalogueType` , and `type` .
status	String	❌	Any valid status value	N/A	The status of the inventory entity (e.g., "ACTIVE").
retailerId	String	✅	Any valid retailer ID	N/A	The retailer ID for which the inventory is uploading.
attributes	Object	❌	Any complex key-value pairs	Keys must be strings; values can be any valid JSON type	Additional attributes for flexible metadata storage.

The following describes the fields which can be submitted as part of an inventory batch record.

Example Request Payload :

1{
2    "action": "UPSERT",
3    "entityType": "INVENTORY",
4    "source": "SAP_ERP",
5    "event" :"InventoryChanged",
6    "catalogueRef": "FUTURE:2",
7      "conditions": {
8    "hasRelatedInventoryQuantities": [
9      {"type": "SALE", "status": "ACTIVE"},
10      {"type": "SALE", "status": "CREATED"},
11      {"type": "CORRECTION", "status": "ACTIVE"}
12    ]
13  },
14    "entities": [
15        {
16            "locationRef": "LOC_MEL",
17            "skuRef": "D45",
18            "qty": 350,
19            "correctedQty": 0,
20            "retailerId": 2,
21            "type": "FUTURE",
22            "ref": "24-MG02:LOC_MELB_RET2:FUTURE",
23            "status": "ACTIVE",
24            "attributes": {
25                "expectedOn": "2024-10-31T00:00:00.00Z", // ISO 8601 format
26                "storageAreaRef": "LOC_MELB_RET2-SR1",
27                "condition": "NEW",
28                "countryOfOrigin": "China",
29                "expiryDate": "2025-12-31T23:59:59.00Z", // ISO 8601 format
30                "supplierId": "SUP12345",
31                "unitOfMeasurement": "PCS",
32                "serialNumber": "SN123456789",
33                "purchaseOrderNumber": "PO987654321",
34                "transferFrom": "STORE01",
35                "inventoryPurpose": "For Sale",
36                "manufacturingBatchInfo": {
37                    "batchNumber": "BATCH001",
38                    "productionDate": "2024-01-15T00:00:00.00Z" // ISO 8601 format
39                }
40                    }
41
42            }
43        
44    ]
45}

Language: json

Name: Example Inventory Batch Request Payload

Description:

Example Inventory Batch Request Payload

Example Response

1{
2  "id": "331"
3}

Language: json

Name: Example Inventory Batch Response

Description:

Example Inventory Batch Response

Inventory Batch API

Overview

Key points

Inventory Batch Submission

Inventory Batch Model

Example Request Payload :

Example Response

Related content

How to Submit Inventory Batches

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links