Fluent Commerce Logo
Docs
Help & Feedback

Submit Inventory Batches With Attributes

How-to Guide

Author:

Fluent Commerce

Changed on:

9 Jan 2025

Key Points

  • Create new Inventory Batches using the Job API 
  • Sample Inventory batch payload 
  • Inventory batch details

Steps

Step arrow right iconAPI Authentication

Authenticate against the Retailer you are sending the Inventory Batch to 

Please follow the Authentication API page 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 New Job to Execute Your Batches

Using the Job API you can create a new Batch Job.
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.
1{
2    "name": "Batch Inventory Job",
3    "retailerId": "{{retailer.id}}"
4}

Language: json

Name: Example payload

Description:

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

Language: json

Name: Example response

Description:

Example response
This ID number is the created job ID. Save this ID as we will use it in the following requests for sending a Batch. This Job ID and the created Job will be used to group subsequent Batches together.

Step arrow right iconCreate and send a new Inventory Batch

Using the Job API you can create an Inventory Batch to be processed under the previously created Job.The URL is using the Job id returned by the last API call, for example 199 as per the previous response.

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
actionString✅"UPSERT"N/ASpecifies the operation on inventory entities (e.g., "UPSERT" to insert/update).Must be a valid action type for inventory operations.
entityTypeString✅"INVENTORY"N/ADefines the type of entity being processed.Must be "INVENTORY".
sourceString❌Any valid source identifier"batch"Identifies the origin of the batch data (e.g., "ERP", "POS").Defaults to "batch" if not provided.
eventString❌Any valid event name"InventoryChanged"Custom event name associated with the batch operation.Defaults to "InventoryChanged" if not provided.
catalogueRefString❌Any valid catalogue reference"DEFAULT:<retailerId>"References the catalogue associated with the inventory batch.Influences `catalogueType` in `ref` construction.
conditionsObject❌Configuration objectUses default transient settingsConfigurations like transient types and statuses are used in de-duplication checks.
entitiesArray✅List of inventory itemsN/AList of inventory itemsFollows the entities object model. Nonconforming inputs are ignored. 


The conditions object has the following fields :

FieldTypeMandatory?Possible ValuesDefault ValueDescription
hasRelatedInventoryQuantitiesArray❌List of transient IQ types and statusesDefault transient types and statusesDefines 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:
FieldTypeMandatory?Possible ValuesConstraintsDescriptionNotes
locationRefString✅Any valid location referenceN/AThe location reference used to match the inventory.
skuRefString✅Any valid SKU referenceN/AThe SKU reference of the inventory item.
qtyInteger✅Any non-negative integerN/AThe quantity to match the on-hand inventory.
correctedQtyInteger❌Any non-negative integerDefaults to 0 if not providedThe current outstanding correction quantity to be saved.
typeString❌Any valid type identifierN/ASpecifies the type of inventory operation (e.g., "LAST_ON_HAND").Defaults to "LAST_ON_HAND" if not provided.
refString❌Any valid referenceMust follow `<skuRef>:<locationRef>:<catalogueType>:<type>`A reference identifier for the inventory entity.If not provided, constructed using `skuRef`, `locationRef`, `catalogueType`, and `type`.
statusString❌Any valid status valueN/AThe status of the inventory entity (e.g., "ACTIVE").
retailerIdString✅Any valid retailer IDN/AThe retailer ID for which the inventory is uploading.
attributesObject❌Any complex key-value pairsKeys must be strings; values can be any valid JSON typeAdditional attributes for flexible metadata storage.
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}

Language: json

Name: Example Inventory Batch Request Payload

Description:

Example Inventory Batch Request Payload
1{
2  "id": "331"
3}

Language: json

Name: Example Inventory Batch Response

Description:

Example Inventory Batch Response
The returned id will be used to check the Batch status in a following call. If you needed to send multiple groups of updates you would run this call for each group of Batches that you are running. If you needed to send 15,000 updates, you would run this 3 times for every 5,000 records( for illustration ) , all under the same Job, using the same job ID.

For a more technical deep dive into how Batch processing works when BPP is enabled, check out this document 

Step arrow right iconCheck Job status

You can use the Job API again to check the status of an existing Job
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: Example response

Description:

Example response

Step arrow right iconCheck Inventory Batch status

You can view the status of a specific Batch as well, this provides a few more details than the previous Job status check.The URL uses the Job id and the Batch id returned by previous APIs.
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: Example response

Description:

Example response
Fluent Commerce

Fluent Commerce

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