Submit Inventory Batches With Attributes

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Authors:

Girish Padmanabha, Kirill Gaiduk

Changed on:

25 May 2026

Key Points

Create inventory batches using the Job API
Sample inventory batch request
Inventory batch processing details

Steps

API authentication

Authenticate against the Retailer you are sending the Inventory Batch to:

Follow the Authentication API for how to authenticate against a Retailer
The returned token will be used to authenticate all the following API calls

Set up a Job

Create a new job to execute your batches using the Job API.

Create Job Example

1POST/{{fluent.account.host}}/api/v4.1/job

1{
2    "name": "Batch Inventory Job",
3    "retailerId": "1",
4    "meta": {
5        "preprocessing": "enabled"
6    }
7}

1{
2    "id": "199"
3}

The `id` is the unique identifier of the created job
Save this `id` to use in subsequent batch requests
Use this `id` to group related batches

Inventory Batch Preprocessing Settings and Behavior in Job API

The `meta` object allows for the inclusion of additional metadata when creating a Job. The currently supported key within `meta` is `preprocessing`, which can influence whether the Batch Preprocessing Process (BPP) is utilized based on the account's settings.The behavior of the `meta.preprocessing` key is governed by the `fc.enable.batch.preprocessing` configuration setting. Below is a table outlining the expected behavior:

`fc.enable.batch.preprocessing `value	`meta.preprocessing` Value	Additional Info in Job Payload	Result
true	"preprocessing": "skip"	BPP should not be used	Do not use BPP
true	"preprocessing": "enabled"	BPP should be used	Use BPP
true	"meta": null or "meta": {}	BPP should be used	Use BPP
true	Omitted or previously created Jobs	BPP should be used	Use BPP
false	Any value	BPP should not be used (overridden)	Do not use BPP

When `fc.enable.batch.preprocessing` is `true`:
- "preprocessing": "skip"
  - Action: BPP should not be used.
- "preprocessing": "enabled" ( any value other than "skip" )
  - Action: BPP should be used.
- "meta": null or "meta": {}
  - Action: BPP should be used.
- Jobs without `meta`
  - Action: BPP should be used.
When `fc.enable.batch.preprocessing` is `false`:
- Regardless of the `meta.preprocessing` value (including `null` or omitted)
  - Action: BPP should not be used.

The fc.enable.batch.preprocessing setting takes precedence over the `meta.preprocessing` value. If fc.enable.batch.preprocessing is set to `FALSE`, BPP will not be used regardless of the `meta.preprocessing` value.
Ensure that when setting `meta.preprocessing`, only the supported values (`"skip"` or `"any value not skip"`) are used to avoid unexpected behavior.
A job-level override will affect only the batches containing inventory data created under the specific job, and this impact will remain in effect until the job expires.

Send an Inventory Batch

Create an inventory batch to be processed under the previously created job using the Job API.

Create Inventory Batch Example

1POST/{{fluent.account.host}}/api/v4.1/job/{jobID}/batch

Reminder

The URL is using the Job ID returned by the last API call, for example `199` as per the previous response: `POST/{{fluent.account.host}}/api/v4.1/job/199/batch`.

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 catalog reference	`DEFAULT:<retailerId>`	References the catalog associated with the inventory 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 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	Default transient types and statuses	Defines custom transient types and statuses for checking during de-duplication, e.g.: `"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 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
`retailerId`	`String`	✅	Any valid retailer ID	N/A	The retailer ID for which the inventory is uploading
`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 `<skuRef>:<locationRef>:<catalogueType>:<type>`	A reference identifier for the inventory entity	If not provided, constructed using: `skuRef` `locationRef` `catalogueType` `type`
`status`	`String`	❌	Any valid status value	N/A	The status of the inventory entity, e.g., `ACTIVE`	The status can be provided in the payload and is used during Batch Pre-Processing for change detection. However, it is not applied or updated by reference `UpsertInventoryQuantity` rule: New Inventory Quantities are created in `CREATED` status and then moved to `ACTIVE` by the `CREATE` ruleset (`SetState` rule) Existing Inventory Quantities keep their current status unless another ruleset/rule changes it
`attributes`	Object	❌	Any complex key-value pairs	Keys must be strings Values can be any valid JSON type	Additional attributes for flexible metadata storage

Request Example

1{
2  "action": "UPSERT",
3  "entityType": "INVENTORY",
4  "source": "ERP",
5  "event" :"InventoryChanged",
6  "catalogueRef": "DEFAULT:1",
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      "retailerId": 1,      
17      "skuRef": "PRDREF1",
18      "locationRef": "LOCREF1",      
19      "ref": "PRDREF1:LOCREF1:DEFAULT:LAST_ON_HAND:1",
20      "qty": 100,
21      "attributes": {
22        "countryOfOrigin": "AU",
23        "manufacturerBatchNumber": "MBN1",        
24        "expiresOn": "2026-09-30T23:59:59Z"
25      }
26    },
27    {
28      "retailerId": 1,
29      "skuRef": "PRDREF1",
30      "locationRef": "LOCREF1",              
31      "ref": "PRDREF1:LOCREF1:DEFAULT:LAST_ON_HAND:2",
32      "qty": 50,
33      "attributes": {
34        "countryOfOrigin": "US",
35        "manufacturerBatchNumber": "MBN2",        
36        "expiresOn": "2026-12-31T23:59:59Z"
37      }
38    },    
39    {
40      "retailerId": 1,        
41      "skuRef": "PRDREF1",
42      "locationRef": "LOCREF1",
43      "type": "ON_ORDER",            
44      "ref": "PRDREF1:LOCREF1:DEFAULT:ON_ORDER:1",
45      "qty": 300,
46      "attributes": {
47        "associationType": "PURCHASE_ORDER",
48        "associationRef": "POREF1",
49        "expectedOn": "2026-06-01T00:00:00Z"
50      }
51    },
52    {
53      "retailerId": 1,        
54      "skuRef": "PRDREF1",
55      "locationRef": "LOCREF1",
56      "type": "ON_ORDER",      
57      "ref": "PRDREF1:LOCREF1:DEFAULT:ON_ORDER:2",      
58      "qty": 150,
59      "attributes": {
60        "parentRef": "PRDREF1:LOCREF1:DEFAULT:ON_ORDER:1",
61        "associationType": "IN_TRANSIT",
62        "associationRef": "ITREF1",
63        "expectedOn": "2026-03-01T00:00:00Z",
64        "countryOfOrigin": "US",
65        "manufacturerBatchNumber": "MBN3",        
66        "expiresOn": "2027-12-31T23:59:59Z"
67      }
68    }     
69  ]
70}

The first two records show `LAST_ON_HAND` inventory segmented by origin, batch, and expiry date
The third record shows future inventory linked to a purchase order
The fourth record shows a related `IN_TRANSIT` future inventory record linked to the purchase order through `parentRef`

1{
2  "id": "331"
3}

The returned `id` is used to check the inventory batch status in subsequent calls

Note

For detailed recommendations on inventory batch sizing, check the Inventory Batch article
For more details on inventory batch processing with batch pre-processing (BPP) enabled, see the Inventory Batch Pre-Processing: Technical Guide with Examples

Check Job Status

Use the Job API to check the status of an existing job.

Get Job Status Example

1GET/{{fluent.account.host}}/api/v4.1/job/{jobID}

1{
2  "jobId": "199",
3  "status": "OPEN",
4  "batch": [
5    {
6      "batchId": "331",
7      "status": "COMPLETE",
8      "createdOn": "2022-10-06T00:31:08.104+0000"
9    }
10  ],
11  "createdOn": "2022-10-06T00:31:08.104+0000"
12}

Check Inventory Batch Status

View the status of a specific batch. This provides more detailed information than the job status.

Get Inventory Batch Status Example

The request requires the Job ID and Batch ID returned by previous API calls.

1GET/{fluent.account.host}/api/v4.1/job/{jobID}/batch/{batchID}

1{
2  "batchId": "331",
3  "entityType": "INVENTORY",
4  "status": "COMPLETE",
5  "start": 1,
6  "count": 10,
7  "total": 0,
8  "results": [],
9  "createdOn": "2022-10-06T00:36:09.344+0000"
10}

Related artifacts

UpsertInventoryQuantity

Inventory Catalog Workflow Template

Virtual Catalog Workflow Templates

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 catalog reference	`DEFAULT:<retailerId>`	References the catalog associated with the inventory 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 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	Default transient types and statuses	Defines custom transient types and statuses for checking during de-duplication, e.g.: `"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 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
`retailerId`	`String`	✅	Any valid retailer ID	N/A	The retailer ID for which the inventory is uploading
`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 `<skuRef>:<locationRef>:<catalogueType>:<type>`	A reference identifier for the inventory entity	If not provided, constructed using: `skuRef` `locationRef` `catalogueType` `type`
`status`	`String`	❌	Any valid status value	N/A	The status of the inventory entity, e.g., `ACTIVE`	The status can be provided in the payload and is used during Batch Pre-Processing for change detection. However, it is not applied or updated by reference `UpsertInventoryQuantity` rule: New Inventory Quantities are created in `CREATED` status and then moved to `ACTIVE` by the `CREATE` ruleset (`SetState` rule) Existing Inventory Quantities keep their current status unless another ruleset/rule changes it
`attributes`	Object	❌	Any complex key-value pairs	Keys must be strings Values can be any valid JSON type	Additional attributes for flexible metadata storage

Submit Inventory Batches With Attributes

Key Points

Steps

API authentication

Set up a Job

Create Job Example

Send an Inventory Batch

Create Inventory Batch Example

Inventory Batch Model

Request Example

Check Job Status

Get Job Status Example

Check Inventory Batch Status

Get Inventory Batch Status Example

Related artifacts

UpsertInventoryQuantity

Inventory Catalog Workflow Template

Virtual Catalog Workflow Templates

Girish Padmanabha

Contributors:

Building Blocks

By Type

Helpful Resources

Quick Links