Author:
Fluent Commerce
Changed on:
12 Feb 2025
Pre-requisites:
This technical guide provides detailed steps on how you can submit Batches to the Fluent platform.
Author:
Fluent Commerce
Changed on:
9 Jan 2025
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.
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 (BPP) is utilized based on the '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:
|
| 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 |
`fc.enable.batch.preprocessing`
is `true`
:`meta`
`fc.enable.batch.preprocessing`
is `false`
:`meta.preprocessing`
value (including `null`
or omitted)`meta.preprocessing`
value. If fc.enable.batch.preprocessing is set to `FALSE`
, BPP will not be used regardless of the `meta.preprocessing`
value.`meta.preprocessing`
, only the supported values (`"skip"`
or `"any value not skip"`
) are used to avoid unexpected behavior.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.
Using the Job API you can create an 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.
The Batch Model consists of:
Field | Type | Mandatory? | Possible Values | Default Value | Description | Notes |
action | String | ✅ | "UPSERT" | N/A | Specifies the operation on entities (e.g., "UPSERT" to insert/update). | Must be a valid type for operations. |
entityType | String | ✅ | "" | N/A | Defines the type of being processed. | Must be "". |
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 name | "InventoryChanged" | Custom 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 batch. | Influences |
conditions | Object | ❌ | Configuration object | Uses default transient settings | Configurations like transient types and statuses are used in de-duplication checks. | |
entities | Array | ✅ | List of items | N/A | List of 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 | Defines custom transient types and statuses for checking during de-duplication
|
Each object within the `entities`
array should follow this structure:
Field | Type | Mandatory? | Possible Values | Constraints | Description | Notes |
locationRef | String | ✅ | Any valid reference | N/A | The reference used to match the . | |
skuRef | String | ✅ | Any valid SKU reference | N/A | The SKU reference of the item. | |
qty | Integer | ✅ | Any non-negative integer | N/A | The quantity to match the on-hand . | |
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 operation (e.g., "LAST_ON_HAND"). | Defaults to "LAST_ON_HAND" if not provided. |
ref | String | ❌ | Any valid reference | Must follow | A reference identifier for the . | If not provided, constructed using |
status | String | ❌ | Any valid status value | N/A | The status of the (e.g., "ACTIVE"). | |
retailerId | String | ✅ | Any valid retailer ID | N/A | The retailer ID for which the 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 works when BPP is enabled, check out this document
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}
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}
Author:
Fluent Commerce
Changed on:
9 Feb 2025
This guide explains how to leverage the `attributes`
object to include custom data in your 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 processes, or integrating with custom workflows. You’ll also learn about recommended fields like `expectedOn`
, `storageAreaRef`
, and `condition`
, which are automatically integrated into workflows for streamlined updates and better data consistency.
`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.`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.`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.`YYYY-MM-DDTHH:MM:SSZ`
) to ensure consistency and proper handling within the system.`attributes`
object with any additional fields relevant to your business processes. The flexibility of this structure allows for robust customization.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 management workflows. This means that these fields will be directly updated in the quantity associated with the incoming record, ensuring seamless operation and enhanced performance.
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 these and make them available within the 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 for your custom implementations.
Attribute Description | Recommended Attribute Key Name | Example | Notes |
Specific storage locations in a . |
| "LOC1-SR-1" | Available in the via |
Date when new stock is expected. |
| "2024-10-31T00:00:00.00Z" | Available in the via |
Information on the manufacturing country. |
| "France" | Available in the via |
Details like production date and . |
|
| Available in the via |
Indicates the last date a product is safe to use. |
| "2025-12-31T23:59:59.00Z" | Available in the via |
Unique identifier for each supplier. |
| "SUP12345" | Available in the via |
Details on how is quantified. Use Case: Ensure consistency in counting, aid in , and simplify stocktaking processes. |
| "PCS" | Available in the via |
Unique identifier for high-value items. |
| "SN123456789" | Available in the via |
Links to specific purchase orders. |
| "PO987654321" | Available in the via |
Source of transfer. |
| "STORE01" | Available in the via |
Purpose of the . |
| "For Sale" | Available in the via |
Indicates the condition of the item. |
| "NEW" | Available in the via |