Inventory Batch API
Author:
Fluent Commerce
Changed on:
24 Mar 2025
Overview
The Batch is designed to send large volumes of data, primarily to update the quantities for positions. While its primary purpose is to handle large-scale updates and ensure the OMS reflects the latest levels after a few days of operations, it is flexible enough to support other types as needed, providing adaptability for diverse management scenarios.
Key points
- Create new Inventory Batches using the Job API
- Sample Inventory batch payload
- Inventory batch details
Inventory Batch Submission
In to create/update data, one can submit an batch using the `/job/{jobId}/batch` endpoint (see link). Multiple can be updated in a single batch by providing multiple `entities`.
Inventory Batch Model
The 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 entities (e.g., "UPSERT" to insert/update). | Must be a valid type for operations. |
entityType | String | ✅ | "" | N/A | Defines the type of being processed. | Must be "". |
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 name | "InventoryChanged" | Custom 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 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 items | N/A | List of 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` array should follow this structure:
Field | Type | Mandatory? | Possible Values | Constraints | Description | Notes |
locationRef | String | ✅ | Any valid reference | N/A | The reference used to match the . | |
skuRef | String | ✅ | Any valid SKU reference | N/A | The SKU reference of the item. | |
qty | Integer | ✅ | Any non-negative integer | N/A | The quantity to match the on-hand . | |
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 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 . | If not provided, constructed using |
status | String | ❌ | Any valid status value | N/A | The status of the (e.g., "ACTIVE"). | |
retailerId | String | ✅ | Any valid retailer ID | N/A | The retailer ID for which the 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 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}Example Response
1{
2 "id": "331"
3}
Examples of Incorrect Entries
1. Null Entry
An entry that is `null` does not conform to the model structure and will be ignored.
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]2. String Instead of Object
A string value in the array is not a valid 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]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]
