Fluent Commerce Logo
Docs
Sign In

Inventory Batch API

Essential knowledge

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 `catalogueType` in `ref` construction.

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

Default transient types and statuses

Defines custom transient types and statuses for checking during de-duplication
       eg) `"hasRelatedInventoryQuantities": `

`[`

` {"type": "SALE", "status": "ACTIVE"}, `

`{"type": "SALE", "status": "CREATED"}, `

`{"type": "CORRECTION", "status": "ACTIVE"} `

`]`




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 `<skuRef>:<locationRef>:<catalogueType>:<type>`

A reference identifier for the .

If not provided, constructed using `skuRef`, `locationRef`, `catalogueType`, and `type`.

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]


Fluent Commerce

Fluent Commerce