Fluent Commerce Logo
Docs
Help & Feedback

Submit Inventory Batches With Attributes

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

Step arrow right iconAPI 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

Step arrow right iconSet 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

Language: markdown

Name: Create Job Endpoint

Description:

Creates a new batch job.
1{
2    "name": "Batch Inventory Job",
3    "retailerId": "1",
4    "meta": {
5        "preprocessing": "enabled"
6    }
7}

Language: json

Name: Create Job Request

Description:

Creates a new batch job with batch pre-processing enabled.
1{
2    "id": "199"
3}

Language: json

Name: Create Job Response

Description:

Returns the `id` of the created job.
  • 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` ValueAdditional Info in Job PayloadResult
true"preprocessing": "skip"BPP should not be usedDo not use BPP
true"preprocessing": "enabled"BPP should be usedUse BPP
true"meta": null or "meta": {}BPP should be usedUse BPP
trueOmitted or previously created JobsBPP should be usedUse BPP
falseAny valueBPP 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.

Step arrow right iconSend 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

Language: markdown

Name: Create Inventory Batch Endpoint

Description:

Creates a new inventory 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
FieldTypeMandatory?Possible ValuesDefault ValueDescriptionNotes
`action``String`✅`UPSERT`N/ASpecifies the operation on inventory entities (e.g., `UPSERT` to insert/update).Must be a valid action type for inventory operations
`entityType``String`✅`INVENTORY`N/ADefines the type of entity being processedMust 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 operationDefaults to `InventoryChanged` if not provided
`catalogueRef``String`❌Any valid catalog reference`DEFAULT:<retailerId>`References the catalog associated with the inventory batchInfluences `catalogueType` in `ref` construction
`conditions`Object❌Configuration objectUses default transient settingsConfigurations like transient types and statuses are used in de-duplication checks
`entities`Array✅List of inventory itemsN/AList of inventory items
  • Follows the entities object model
  • Nonconforming inputs are ignored 
The `conditions` object has the following fields:
FieldTypeMandatory?Possible ValuesDefault ValueDescription
`hasRelatedInventoryQuantities`Array❌List of transient IQ types and statusesDefault transient types and statusesDefines 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:
FieldTypeMandatory?Possible ValuesConstraintsDescriptionNotes
`locationRef``String`✅Any valid location referenceN/AThe location reference used to match the inventory
`skuRef``String`✅Any valid SKU referenceN/AThe SKU reference of the inventory item
`qty``Integer`✅Any non-negative integerN/AThe quantity to match the on-hand inventory
`retailerId``String`✅Any valid retailer IDN/AThe retailer ID for which the inventory is uploading
`correctedQty``Integer`❌Any non-negative integerDefaults to 0 if not providedThe current outstanding correction quantity to be saved
`type``String`❌Any valid type identifierN/ASpecifies the type of inventory operation, e.g., `LAST_ON_HAND`Defaults to `LAST_ON_HAND` if not provided
`ref``String`❌Any valid referenceMust follow `<skuRef>:<locationRef>:<catalogueType>:<type>`A reference identifier for the inventory entityIf not provided, constructed using:
  • `skuRef`
  • `locationRef`
  • `catalogueType`
  • `type`
`status``String`❌Any valid status valueN/AThe 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}

Language: json

Name: Create Inventory Batch Request

Description:

Creates a new inventory batch.
  • 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}

Language: json

Name: Create Inventory Batch Response

Description:

Returns the `id` of the created inventory batch.
  • The returned `id` is used to check the inventory batch status in subsequent calls

Step arrow right iconCheck 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}

Language: markdown

Name: Get Job Status Endpoint

Description:

Retrieves the status of an existing job.Example:`GET/{{fluent.account.host}}/api/v4.1/job/199`
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}

Language: json

Name: Get Job Status Response

Description:

Returns the current status of the job, including its state and associated batch(es) details.

Step arrow right iconCheck 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}

Language: markdown

Name: Get Inventory Batch Status Endpoint

Description:

Retrieves the status of an existing inventory batch.Example:`GET/{fluent.account.host}/api/v4.1/job/199/batch/331`
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}

Language: json

Name: Get Inventory Batch Status Response

Description:

Returns the current status of the inventory batch, including its state and processing details.

Related artifacts

UpsertInventoryQuantity
Inventory Catalog Workflow Template
Virtual Catalog Workflow Templates
Girish Padmanabha

Girish Padmanabha

Contributors:
Kirill Gaiduk
Building Blocks
Building Blocks
Packages & Modules
All UI Components
Workflows
Settings
Interface Contracts
All Rules
By Type
All Types
Knowledge Tracks
Extend Knowledge
Glossary
All How-to Guides
Sitemap
Topics
Use Cases
Helpful Resources
Platform Limits
Support Policy
Service Level Agreement (SLA) - Enterprise
Deprecation Policy
Extend Knowledge Content – Terms and Conditions
System and Organization Controls (SOC) 3 Report
Data Privacy Addendum
Security Policy
Quick Links
For Partners
Customer Resources
Webinars and Events
Certifications
Training Resources
Knowledge Tracks
Builders Portal
Product Update Newsletter
Industry Blogs & Events Newsletter
Trust Center Portal

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Fluent Logo