How to use Direct Inventory Updates

Topic

Author:

Fluent Commerce

Changed on:

11 Sept 2024

Overview

Direct Inventory Updates are one of the two reference ways to send last-on-hand inventory updates into your inventory workflows. Direct Inventory Updates are best used when you have a small volume of inventory updates (maximum of 1000 updates).

Introduction

Author:

Fluent Commerce

Changed on:

11 Sept 2024

Overview

As part of the Inventory Module, we have provided a reference implementation. This includes the workflow JSON, rules, & configurations required to implement direct inventory updates.

Key points

Direct updates are designed to be used when the number of Inventory updates is quite small, less than 1000 updates
Capabilities of the platform this process uses
Supplementary guides

When should you use direct updates?

Direct updates are designed for use when the number of Inventory updates is quite small, less than 1000. Using direct updates results in quicker processing of inventory vs. batch uploads when operating at these lower inventory volumes.

Direct updates are best used in conjunction with batch inventory updates. When a specific job has 1000 or fewer updates, direct updates should be used; if the job has more than 1000 updates, the batch should be used.

Capabilities of the platform this process uses

Capability	Description
Event API	API to send the events against

Supplementary guides

Guide	Description
How to send Delta Inventory updates	Learn how to send delta inventory updates via events
How to use Inventory Batches	Learn how to use Inventory Batches and follow the suggested best practices

Send Direct updates

Author:

Fluent Commerce

Changed on:

11 Sept 2024

Key Points

Perform smaller inventory updates by sending an event into your workflow via event API.

Steps

Step 1: Authenticate against the Retailer you are sending the direct updates

For use of authentication please read: Authentication

The returned token will be used for later API calls.

Step 2: Send the direct inventory update event request

To send a direct update you need to ensure your data matches the below type. This will be a JSON object with the defined fields populated.

*Parameter*	*Description*	*Data Type*
ref	ref	String
type	The inventory position type	String
productRef	The ref of the variant product associated with the inventory position	String
locationRef	The location ref associated with the inventory position	String
qty	The quantity	Integer
correctedQty	corrected quantity	Integer
inventoryQuantity	Extra optional attributes sent as part of the payload	JSON

Example URL

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

1{
2  "name": "INVENTORY_UPDATE",
3  "accountId": "YOUR_ACCOUNT",
4  "retailerId": "1",
5  "entityRef": "DEFAULT:2",
6  "entityType": "INVENTORY_CATALOGUE",
7  "entitySubtype": "DEFAULT",
8  "rootEntityType": "INVENTORY_CATALOGUE",
9  "rootEntityRef": "DEFAULT:2",
10  "attributes": 
11    { 
12      "inventoryUpdates": 
13      [ 
14        { 
15          "ref" : "testref1",
16          "productRef": "D45",
17          "locationRef": "LOC_MEL",
18          "qty": 350,
19          "correctedQty":0,
20          "type":"DEFAULT" 
21        } 
22      ]
23    }
24}

Language: json

Name: Example payload

Description:

Example inventory payload with no attributes for INVENTORY_UPDATE event .

How to Implement Enhanced Inventory Attributes in Your Payloads

Author:

Fluent Commerce

Changed on:

11 Sept 2024

Overview

This guide is designed to help you implement the enhanced

`attributes`

functionality in your inventory payloads. The

`attributes`

object is a flexible structure that allows you to include a wide range of key-value pairs, including complex JSON objects and arrays. This flexibility enables you to customize the data according to your specific business needs, whether you are managing detailed product information, handling sophisticated supply chain operations, or integrating with custom workflows.

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, and these will be accessible within the workflow for your custom implementations.

Recommended Attributes Table

Attribute Description	Recommended Attribute Key Name	Category	Example	Notes	Use Case
Specific storage locations in a warehouse.	`storageAreaRef`	Warehouse Management	"LOC1-SR-1"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.storageAreaRef` and automatically updated in the inventory quantity associated with the incoming record.	Optimizing space utilization, reducing retrieval time, and improving warehouse efficiency.
Date when new stock is expected.	`expectedOn`	Supply Chain Management	"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.	Planning for space allocation, staffing, and ensuring timely product availability.
Information on the manufacturing country.	`countryOfOrigin`	Compliance/Localization	"France"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.countryOfOrigin` and can be used in custom rules. Alternate field name for this madeIn	Compliance with import/export regulations, supporting marketing strategies emphasizing local products.
Details like production date and location.	`manufacturingBatchInfo`	Product Tracking	{ "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.	Tracking production details, quality control, and recall management.
Indicates the last date a product is safe to use.	`expiryDate`	Product Lifecycle	"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.	Managing stock rotation, reducing waste, and ensuring compliance with health and safety regulations.
Unique identifier for each supplier.	`supplierId`	Vendor Management	"SUP12345"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.supplierId` and can be used in custom rules.	Tracking supplier performance, managing vendor relationships, and optimizing supply chain efficiency.
Details on how inventory is quantified.	`unitOfMeasurement`	Inventory Specification	"PCS"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.unitOfMeasurement` and can be used in custom rules.	Ensure consistency in inventory counting, aid in order fulfillment, and simplify stocktaking processes.
Unique identifier for high-value items.	`serialNumber`	Item Identification	"SN123456789"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.serialNumber` and can be used in custom rules.	Tracking individual items, managing warranties, and enhancing theft prevention.
Links inventory to specific purchase orders.	`purchaseOrderNumber`	Procurement Tracking	"PO987654321"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.purchaseOrderNumber` and can be used in custom rules.	Matching received goods with purchase orders, improving procurement tracking, and enhancing order accuracy.
Source of inventory transfer.	`transferFrom`	Inventory Movement	"STORE01"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.transferFrom` and can be used in custom rules.	Tracking inventory movement between locations for internal auditing.
Purpose of the inventory.	`inventoryPurpose`	Inventory Utilization	"For Sale"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.inventoryPurpose` and can be used in custom rules.	Differentiating stock based on its intended use, aiding in inventory accounting and management.
Indicates the condition of the inventory item.	`condition`	Inventory Condition	"NEW"	Available in the workflow via `inventoryPosition.inventoryQuantity.attributes.condition ` and automatically updated in the inventory quantity associated with the incoming record.	Managing inventory condition, enabling categorization of items for different sales channels.

1
2{
3  "name": "INVENTORY_UPDATE",
4  "accountId": "YOUR_ACCOUNT",
5  "retailerId": "1",
6  "entityRef": "DEFAULT:2",
7  "entityType": "INVENTORY_CATALOGUE",
8  "entitySubtype": "DEFAULT",
9  "rootEntityType": "INVENTORY_CATALOGUE",
10  "rootEntityRef": "DEFAULT:2",
11  "attributes": 
12    { 
13      "inventoryUpdates": 
14      [ 
15        { 
16          "ref" : "testref1",
17          "productRef": "D45",
18          "locationRef": "LOC_MEL",
19          "qty": 350,
20          "correctedQty":0,
21          "type":"DEFAULT" ,
22          "inventoryQuantity": {
23             "attributes": {
24                "expectedOn": "2024-10-31T00:00:00.00Z", // ISO 8601 format
25                "storageAreaRef": "LOC_MELB_RET2-SR1",
26                "condition": "NEW",
27                "countryOfOrigin": "China",
28                "expiryDate": "2025-12-31T23:59:59.00Z", // ISO 8601 format
29                "supplierId": "SUP12345",
30                "unitOfMeasurement": "PCS",
31                "serialNumber": "SN123456789",
32                "purchaseOrderNumber": "PO987654321",
33                "transferFrom": "STORE01",
34                "inventoryPurpose": "For Sale",
35                "manufacturingBatchInfo": {
36                    "batchNumber": "BATCH001",
37                    "productionDate": "2024-01-15T00:00:00.00Z" // ISO 8601 format
38                }
39                    }
40        } 
41      ]
42    }
43}

Language: json

Name: Example payload with enhanced payload for direct updates via INVENTORY_UPDATE event

Description:

Example payload with enhanced payload for direct updates via INVENTORY_UPDATE event

Payload size limits for Direct Updates

The size of direct inventory updates is 1,000 records per request. Sending more than 1,000 records in a request will fail the event at the rule level.

How to use Direct Inventory Updates

Overview

Introduction

Overview

Key points

When should you use direct updates?

Capabilities of the platform this process uses

Supplementary guides

Send Direct updates

Key Points

Steps

Step 1: Authenticate against the Retailer you are sending the direct updates

Step 2: Send the direct inventory update event request

How to Implement Enhanced Inventory Attributes in Your Payloads

Overview

Key points

Leveraging Recommended Attributes

Flexibility for Custom Attributes

Recommended Attributes Table

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links