Inventory Batch API
Author:
Fluent Commerce
Changed on:
24 Mar 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``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 |
conditions | Object | ❌ | Configuration object | Uses default transient settings | Configurations like transient types and statuses are used in de-duplication checks. | |
entities | Array | ✅ | List of inventory items | N/A | List of inventory items | Follows the entities object model. Nonconforming inputs are ignored. |
The conditions object has the following fields :
Field | Type | Mandatory? | Possible Values | Default Value | Description |
hasRelatedInventoryQuantities | Array | ❌ | List of transient IQ types and statuses | Defines custom transient types and statuses for checking during de-duplication |
Each object within the
`entities`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 | A reference identifier for the inventory entity. | If not provided, constructed using |
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
Examples of Incorrect Entries
1. Null Entry
An entry that is
`null`1"entities": [
2 null,
3 {
4 "locationRef": "LOC_MEL",
5 "skuRef": "D45",
6 "qty": 350,
7 "correctedQty": 0,
8 "retailerId": 2,
9 "type": "FUTURE",
10 "ref": "24-MG02:LOC_MELB_RET2:FUTURE",
11 "status": "ACTIVE",
12 "attributes": { /* valid attributes */ }
13 }
14]Language: plain_text
Name: entities array with null value
Description:
entities array with null value
2. String Instead of Object
A string value in the array is not a valid entity object and is thus ignored.
1"entities": [
2 "Invalid Entry",
3 {
4 "locationRef": "LOC_MEL",
5 "skuRef": "D45",
6 "qty": 350,
7 "correctedQty": 0,
8 "retailerId": 2,
9 "type": "FUTURE",
10 "ref": "24-MG02:LOC_MELB_RET2:FUTURE",
11 "status": "ACTIVE",
12 "attributes": { /* valid attributes */ }
13 }
14]Language: json
Name: entities array has a string value
Description:
entities array has a string value
3. Number Instead of Object
Similarly, a numeric entry does not meet the required structure and is ignored.
1"entities": [
2 12345,
3 {
4 "locationRef": "LOC_MEL",
5 "skuRef": "D45",
6 "qty": 350,
7 "correctedQty": 0,
8 "retailerId": 2,
9 "type": "FUTURE",
10 "ref": "24-MG02:LOC_MELB_RET2:FUTURE",
11 "status": "ACTIVE",
12 "attributes": { /* valid attributes */ }
13 }
14]Language: json
Name: entities array with numeric input
Description:
entities array with numeric input
