In what use cases can you use Inventory Batches

The primary use cases you should be using Inventory Batches:

• Sending periodic updates of stock from the Inventory source of truth; in typical architectures, this will be an ERP that has collected all Inventory Updates during the last cycle (typically daily).
• Informing the OMS of the latest stocktake ensures that the OMS is aware of any changes that may have been manually handled, e.g., missing or damaged stock.

Capabilities of the platform this process uses

After using this document, you will be able to run an Inventory Batch. If you need to extend or build on this document's capabilities, the below pages will link to the core capabilities used.

Leveraging Recommended Attributes

While the

`attributes`

`expectedOn`

`storageAreaRef`

`condition`

Flexibility for Custom Attributes

Beyond the recommended attributes, you have the flexibility to include additional fields that are specific to your business requirements. Whether you need to send simple key-value pairs, nested JSON structures, or arrays, our system will process these and make them available within the workflow via

`inventoryPosition.inventoryQuantity.attributes.<fieldname>`

The table below provides examples of the recommended attributes along with their descriptions, usage, and examples. However, you are not limited to these fields—you can extend the

`attributes`

Recommended Attributes Table

`storageAreaRef`

`inventoryPosition.inventoryQuantity.attributes.storageAreaRef`

`expectedOn`

`inventoryPosition.inventoryQuantity.attributes.expectedOn`

`countryOfOrigin`

`inventoryPosition.inventoryQuantity.attributes.countryOfOrigin`

`manufacturingBatchInfo`

`inventoryPosition.inventoryQuantity.attributes.manufacturingBatchInfo`

`expiryDate`

`inventoryPosition.inventoryQuantity.attributes.expiryDate`

`supplierId`

`inventoryPosition.inventoryQuantity.attributes.supplierId`

`unitOfMeasurement`

`inventoryPosition.inventoryQuantity.attributes.unitOfMeasurement`

`serialNumber`

`inventoryPosition.inventoryQuantity.attributes.serialNumber`

`purchaseOrderNumber`

`inventoryPosition.inventoryQuantity.attributes.purchaseOrderNumber`

`transferFrom`

`inventoryPosition.inventoryQuantity.attributes.transferFrom`

`inventoryPurpose`

`inventoryPosition.inventoryQuantity.attributes.inventoryPurpose`

`condition`

`inventoryPosition.inventoryQuantity.attributes.condition `

Example payload with enhanced inventory payload via Batch API ( BPP enabled)

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

Example payload with enhanced inventory payload for direct updates via INVENTORY_UPDATE event

1
2{
3  "name": "INVENTORY_UPDATE",
4  "accountId": "YOUR_ACCOUNT",
5  "retailerId": "1",
6  "entityRef": "DEFAULT:2",
7  "entityType": "INVENTORY_CATALOGUE",
8  "entitySubtype": "DEFAULT",
9  "rootEntityType": "INVENTORY_CATALOGUE",
10  "rootEntityRef": "DEFAULT:2",
11  "attributes": 
12    { 
13      "inventoryUpdates": 
14      [ 
15        { 
16          "ref" : "testref1",
17          "productRef": "D45",
18          "locationRef": "LOC_MEL",
19          "qty": 350,
20          "correctedQty":0,
21          "type":"DEFAULT" ,
22          "inventoryQuantity": {
23             "attributes": {
24                "expectedOn": "2024-10-31T00:00:00.00Z", // ISO 8601 format
25                "storageAreaRef": "LOC_MELB_RET2-SR1",
26                "condition": "NEW",
27                "countryOfOrigin": "China",
28                "expiryDate": "2025-12-31T23:59:59.00Z", // ISO 8601 format
29                "supplierId": "SUP12345",
30                "unitOfMeasurement": "PCS",
31                "serialNumber": "SN123456789",
32                "purchaseOrderNumber": "PO987654321",
33                "transferFrom": "STORE01",
34                "inventoryPurpose": "For Sale",
35                "manufacturingBatchInfo": {
36                    "batchNumber": "BATCH001",
37                    "productionDate": "2024-01-15T00:00:00.00Z" // ISO 8601 format
38                }
39                    }
40        } 
41      ]
42    }
43}

Inventory Data Integration Guidelines

When sending inventory data to the batch endpoint with BPP enabled, please adhere to the following guidelines to ensure successful processing:

Batch Size Limits:

• Each batch of inventory data must not exceed 10MB in total size.
• You can include up to 1,000 items per batch if each item is 10KB in size.

Batch Item Size:

• It is recommended that each individual batch item be a maximum of 10KB in size, including both the fixed part of the payload and any key-value pairs of attributes.

Attributes in Inventory Data:

• Attributes can include complex data types such as JSON objects, arrays, booleans, numbers, and strings.
• While there is no specific limit on the number of attributes, we recommend including only relevant data and keeping the size of attributes as small as possible to ensure more efficient processing.

General Structure:

• Ensure that the fixed part of the payload (e.g., 

  `locationRef`

  , 

  `skuRef`

  , 

  `qty`

  , 

  `correctedQty`

  , 

  `retailerId`

  ) is included as required.
• The remaining size, after accounting for the fixed part, should be allocated to the attributes.

Encoding:

• Use UTF-8 encoding for all data. Standard ASCII characters are recommended to optimize space.

Visibility of successful Batch processing

The current best tool for visibility is to use the orchestration_audit events to understand the success and failures of Inventory Updates sent via batch. This provides visibility into the individual items included in the Batches.

Note: Right now, only Failures & Exception audit events are visible for Inventory.

Supplementary guides

After you have followed this guide and understand how to use Inventory Batches, we suggest reading a few more guides to enhance the usability of your Inventory implementation.