Inventory Catalogue Workflow Interface Contracts
Interface Contract
Changed on:
31 Aug 2026
Detailed Description
The below Interface Contracts document the interaction points with the Inventory Catalogue workflow. These allow you to ensure that any integration made into the workflow will enable the workflow to work correctly.
Item Definition
UpdateInventoryQty Event
This event is used anytime an external (anything from outside this workflow) creation of inventory quantities is triggered.Request Payload
| Property | Description | Type | Required? |
| items | The list of items whose inventory positions to be updated | List | Required |
| Property | Description | Type | Required? | Notes |
`fulfilmentId` | The fulfilment ID against which the inventory quantities are to be created/updated | String | Required | |
`skuRef` | The SKU reference of the inventory position | String | Required | |
`locationRef` | The SKU reference of the inventory position | String | Required | |
`reserveQty` | The count of RESERVED quantities | Int | Conditional | Only required when reserve stock |
`correctionQty` | The count of CORRECTED quantities | Int | Conditional | Only required when confirm a fulfilment |
`saleQty` | The count of SALE quantities | Int | Conditional | Only required when confirm a fulfilment |
`cancelQty` | The count of CANCELLED quantities | Int | Conditional | Only required when cancel a fulfilment |
Event Request Example
1{
2 "name": "UpdateInventoryQty",
3 "retailerId": "{{retailer.id}}",
4 "entityRef": "{{inventoryCatalogue.ref}}",
5 "entityType": "INVENTORY_CATALOGUE",
6 "entitySubtype": "{{inventoryCatalogue.type}}",
7 "rootEntityType": "INVENTORY_CATALOGUE",
8 "rootEntityRef": "{{inventoryCatalogue.ref}}",
9 "attributes": {
10 "items": [
11 {
12 "skuRef": "{{product.ref}}",
13 "locationRef": "{{location.ref}}",
14 "fulfilmentId": "100",
15 "reserveQty": -5,
16 "correctionQty": 0,
17 "saleQty": 0,
18 "cancelQty": 0
19 }
20 ]
21 }
22}Inventory Batch Event
This event is generated by the Inventory Batch API and is defined in the`event` field of the batch payload (see Submit Inventory Batches With Attributes)Request Payload
| Property | Description | Type | Required? |
| inventoryPosition | The inventory position that has changed | Object | Required |
`source` | The batch source system | String | Optional |
`trailLogs` | The job and batch lineage | Array | Optional |
`inventoryPosition` Definition| Property | Description | Type | Required | Notes |
`ref` | The inventory position reference | String | Optional | Format: `locationRef:productRef` |
`productRef` | The product reference associated with the inventory position | String | Required | |
`locationRef` | The location reference associated with the inventory position | String | Required | |
`qty` | The quantity associated with the inventory position | Integer | Required | |
`correctedQty` | The corrected quantity | Integer | Deprecated | |
`inventoryQuantity` | Additional inventory quantity data | Object | Optional | Contains custom quantity details and attributes |
`inventoryQuantity` Definition
| Property | Description | Type | Required | Notes |
`ref` | Reference for the custom inventory quantity | String | Optional | |
`type` | Type of the custom inventory quantity | String | Optional | E.g., `"PURCHASE_ORDER"` |
`status` | Status of the custom inventory quantity | String | Optional | E.g., `"ACTIVE"` |
`attributes` | Custom attributes for the custom inventory quantity | Object | Optional | Contains key-value pairs for additional data |
1{
2 "name": "InventoryChanged", //matching the `event` field in the batch payload
3 "accountId": "{{account.id}}",
4 "retailerId": "{{retailer.id}}",
5 "entityRef": "{{inventoryCatalogue.ref}}",
6 "entityType": "INVENTORY_CATALOGUE",
7 "entitySubtype": "{{inventoryCatalogue.type}}",
8 "rootEntityType": "INVENTORY_CATALOGUE",
9 "rootEntityRef": "{{inventoryCatalogue.ref}}",
10 "source": "your-batch-source", // Optional
11 "trailLogs": [
12 "job:{{job.id}}",
13 "batch:{{batch.id}}"
14 ],
15 "attributes": {
16 "inventoryPosition": {
17 "ref": "{{location.ref}}:{{product.ref}}", // optional, format: "locationRef:productRef"
18 "productRef": "{{product.ref}}",
19 "locationRef": "{{location.ref}}",
20 "qty": 40,
21 "correctedQty": 0, // deprecated
22 "inventoryQuantity": { // optional
23 "ref": "{{inventoryQuantity.ref}}", // optional
24 "type": "{{inventoryQuantity.type}}", // optional
25 "status": "{{inventoryQuantity.status}}", // optional
26 "attributes": { // optional, additional attributes e.g. countryOfOrigin, expectedOn, associationRef etc.
27 ...
28 }
29 }
30 }
31 }
32}
33