How to Submit Inventory Batches

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Topic

Author:

Fluent Commerce

Changed on:

12 Feb 2025

Overview

Pre-requisites:

You should have knowledge of Inventory Batch
You should have knowledge of Inventory Batch Pre-Processing

This technical guide provides detailed steps on how you can submit Inventory Batches to the Fluent platform.

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

API 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.

Set 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` 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.

Example URL

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

1{
2    "name": "Batch Inventory Job",
3    "retailerId": "{{retailer.id}}"
4}

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

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.

Create 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.

Example URL

`POST/{{fluent.account.host}}/api/v4.1/job/{jobID}/batch`Example:`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 catalogue reference	"DEFAULT:<retailerId>"	References the catalogue 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 eg) `"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.
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`, and `type`.
status	String	❌	Any valid status value	N/A	The status of the inventory entity (e.g., "ACTIVE").
retailerId	String	✅	Any valid retailer ID	N/A	The retailer ID for which the inventory is uploading.
attributes	Object	❌	Any complex key-value pairs	Keys must be strings; values can be any valid JSON type	Additional 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}

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

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

Check Job status

You can use the Job API again to check the status of an existing Job

Example URL

`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}

Check 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.

Example URL

`GET/{fluent.account.host}/api/v4.1/job/199{jobID}batch/{batchID}`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}

Author:

Fluent Commerce

Changed on:

9 Feb 2025

Overview

This guide explains how to leverage the `attributes` object to include custom data in your inventory payloads. By supporting both simple key-value pairs and complex JSON structures, the `attributes` object offers the flexibility to meet diverse business requirements—whether you’re managing detailed product information, optimizing warehouse processes, or integrating with custom workflows. You’ll also learn about recommended attribute fields like `expectedOn`, `storageAreaRef`, and `condition`, which are automatically integrated into Inventory workflows for streamlined updates and better data consistency.

Key points

Flexible Attribute Structure: The `attributes` object supports any combination of key-value pairs, including complex JSON structures and arrays. This flexibility allows you to customize the data sent in your inventory payloads to meet specific business needs.
Recommended Attributes: Certain key attributes, such as `expectedOn`, `storageAreaRef`, and `condition`, are automatically integrated into our platform’s workflows. These fields will be directly updated in the inventory quantity associated with the incoming record, facilitating seamless integration with existing fields.
Custom Attribute Availability: Any custom attributes that you include in the `attributes` object will be available in workflows via `inventoryPosition.inventoryQuantity.attributes.<fieldname>`. This enables you to incorporate custom data into rule-based processes or other logic tailored to your business requirements.
ISO 8601 Date Format: For any date-related attributes, it is recommended to use the ISO 8601 format (e.g., `YYYY-MM-DDTHH:MM:SSZ`) to ensure consistency and proper handling within the system.
Integration with Workflows: The system is designed to handle both recommended and custom attributes, making them accessible within the workflow context. This ensures that you can leverage these attributes in custom rules and other logic, depending on the specific needs of your implementation.
Extensibility: While the table of recommended attributes provides a useful starting point, you are encouraged to extend the `attributes` object with any additional fields relevant to your business processes. The flexibility of this structure allows for robust customization.

Prerequisite: Workflow and Plugin Requirements

Important Note : To fully leverage the extended attributes functionality within the inventory payload, ensure that you are using the Reference Inventory Workflow and Plugin Version 1.4 or later.

Leveraging Recommended Attributes

While the `attributes` object gives you the freedom to define and send any custom fields, we recommend using certain key attributes that are optimized for our platform. These recommended fields, such as `expectedOn`, `storageAreaRef`, and `condition`, are automatically integrated into our platform’s inventory management workflows. This means that these fields will be directly updated in the inventory quantity associated with the incoming record, ensuring seamless operation and enhanced performance.

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>`. This allows you to incorporate your custom data into rule-based processes or other logic tailored to your specific business scenarios.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` object with any custom fields that meet your needs. These will be accessible within the workflow for your custom implementations.

Recommended Attributes Table

Attribute Description	Recommended Attribute Key Name	Example	Notes
Specific storage locations in a warehouse. Use Case : Optimizing space utilization, reducing retrieval time, and improving warehouse efficiency.	`storageAreaRef`	"LOC1-SR-1"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.storageAreaRef` and automatically updated in the inventory quantity associated with the incoming record.
Date when new stock is expected. Use Case : Planning for space allocation, staffing, and ensuring timely product availability.	`expectedOn`	"2024-10-31T00:00:00.00Z"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.expectedOn` and automatically updated in the inventory quantity associated with the incoming record. Recommended date format is ISO 8601.
Information on the manufacturing country. Use Case : Compliance with import/export regulations, supporting marketing strategies emphasizing local products.	`countryOfOrigin`	"France"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.countryOfOrigin` and can be used in custom rules. Alternate field name for this madeIn
Details like production date and location. Use Case : Tracking production details, quality control, and recall management.	`manufacturingBatchInfo`	`{ "batchNumber": "BATCH001", "productionDate": "2024-01-15T00:00:00.00Z" }`	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.manufacturingBatchInfo` and can be used in custom rules. Production date should be in ISO 8601 format.
Indicates the last date a product is safe to use. Use Case : Managing stock rotation, reducing waste, and ensuring compliance with health and safety regulations.	`expiryDate`	"2025-12-31T23:59:59.00Z"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.expiryDate` and can be used in custom rules. Recommended date format is ISO 8601.
Unique identifier for each supplier. Use Case : Tracking supplier performance, managing vendor relationships, and optimizing supply chain efficiency.	`supplierId`	"SUP12345"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.supplierId` and can be used in custom rules.
Details on how inventory is quantified.Use Case:Ensure consistency in inventory counting, aid in order fulfillment, and simplify stocktaking processes.	`unitOfMeasurement`	"PCS"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.unitOfMeasurement` and can be used in custom rules.
Unique identifier for high-value items. Use Case: Tracking individual items, managing warranties, and enhancing theft prevention.	`serialNumber`	"SN123456789"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.serialNumber` and can be used in custom rules.
Links inventory to specific purchase orders. Use Case: Matching received goods with purchase orders, improving procurement tracking, and enhancing order accuracy.	`purchaseOrderNumber`	"PO987654321"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.purchaseOrderNumber` and can be used in custom rules.
Source of inventory transfer. Use Case: Tracking inventory movement between locations for internal auditing.	`transferFrom`	"STORE01"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.transferFrom` and can be used in custom rules.
Purpose of the inventory. Use Case: Differentiating stock based on its intended use, aiding in inventory accounting and management.	`inventoryPurpose`	"For Sale"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.inventoryPurpose` and can be used in custom rules.
Indicates the condition of the inventory item. Use Case: Managing inventory condition, enabling categorization of items for different sales channels.	`condition`	"NEW"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.condition `and automatically updated in the inventory quantity associated with the incoming record.

How to Submit Inventory Batches

Overview

Submit Inventory Batches With Attributes

Key Points

Steps

API Authentication

Authenticate against the Retailer you are sending the Inventory Batch to

Set Up a New Job to Execute Your Batches

Create and send a new Inventory Batch

Inventory Batch Model

Check Job status

Check Inventory Batch status

How to Use Enhanced Inventory Attributes in Your Payloads

Overview

Key points

Prerequisite: Workflow and Plugin Requirements

Leveraging Recommended Attributes

Flexibility for Custom Attributes

Recommended Attributes Table

Related content

Inventory Batch Pre-Processing

How Inventory Batch Pre-Processing works

Enable Batch Inventory Pre-Processing

Inventory Batch Pre-Processing: Technical Guide with Examples

Job API

Fluent Commerce

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links