Inventory Import File

The Inventory Import process provides current stock-level information to Kibo. This data helps Kibo accurately assign orders to fulfillment locations and set product availabilities. If you have multiple fulfillment locations, you use inventory data to manage inventory levels at each location and assign orders to them appropriately.

Types of Inventory Import

Two types of Inventory Import processes exist: Refreshes and Updates. Refreshes are more comprehensive and usually sent once per day, providing the total count for all products in the catalog. Updates are normally sent every hour and provide an adjustment to the values sent in the previous Refresh, indicating which product counts should be increased or decreased.

Refresh File Attributes

Delivered to Kibo once each day
Represents an accurate stock count for all products
Includes products with a stock count of zero (0)

Update File Attributes

Delivered to Kibo throughout the day
Increments (+2) or decrements (-2) existing stock count(s)
Sometimes called a ‘trickle’ feed

Getting Started

You must prepare either an SFTP (Secure File Transfer Protocol) site, S3 bucket, or GCS bucket where Kibo can pick up inventory files. Use the Save Fetch Config API to provide its information to Kibo, including the remote path and remote path archive for the file transmission location. Some different fields are required depending on whether you’re setting up SFTP, S3, or GCS. These are labelled in the field names and descriptions of the Save Fetch Config schema (which will be updated soon with GCS fields). The below example would configure a GCS bucket:

{
    "active": true,
    "refreshEnabled": true,
    "gcsBucket": "bucket_1",
    "gcsPath": "path_1",
    "gcsArchivePath": "arch_path_1",
    "lockName": "lock",
    "postProcessAction": 1,
    "refreshFileDescription": "refreshinventory"
}

SFTP Best Practices

Kibo recommends following the below guidelines to maximize SFTP performance. These suggestions apply to any file pickup and ingestion processes from the client-side or third party SFTP droppoint, as well as Kibo’s own file delivery.

Ensuring access to the SFTP droppoint is the responsibility of the client or a third party maintainer. Make sure that Kibo’s SFTP user has read and write permissions to the directory, which is required to deliver files.
- For example, in the command line this may look like drw-rw-r-- (which means the owner has read/write, the group has read/write, others are read-only)
Ensure files do not pile up over time → utilize /archive folders and periodic cleanup of historic data. Monitor the droppoint and clean up files that are no longer needed.
- If you need to retain the files, archive them to another folder once they’ve been processed.
Ensure disk space usage is monitored and alerts the maintaining IT team in time to address low disk space situations before causing connection issues for Kibo.

Create and Upload Inventory Files

Inventory data should be submitted as XML or CSV files and compressed into Zip format before being transferred. A Trigger/Control file should also be created each time data is submitted. The Trigger file tells Kibo that the inventory file is ready to process. This is an empty file with the same file name as the inventory files being submitted, and the extension .done (ex. T_{tenantId}_REFRESH_130909121152.zip.done). The zipped file should be uploaded to the SFTP or S3/GCS bucket followed by the Trigger file. For optimal efficiency and timely data processing, please ensure that all submitted Refresh and Update files are populated with inventory data. As a best practice, your automated processes should be configured to prevent the unnecessary transmission of empty files without inventory data to Kibo.

Naming Inventory Import Files

Inventory files should be named with the following conventions, depending on what type of inventory import it is:

T_{tenantId}_REFRESH_YYMMDDhhmmss
T_{tenantId}_UPDATE_YYMMDDhhmmss

Where:

{tenantId} is the Kibo-assigned tenant ID (for example, 3456)
REFRESH identifies this file as a Refresh
UPDATE identifies this file as an Update
YYMMDD is the year, month, and day represented in two-digit format. For example, 130301 is March 1, 2013
hhmmss is the time in Pacific Standard Military Time, expressed as hour-minute-second, that the file was created. For example, 205912 is 10:59:12 p.m. PT.

Data Elements

These parameters are used in both CSV and XML file formats. When building the file, identify a location name and then follow it with blocks of the item-specific data for each product.

Field	Required	Format	Description
LocationCode	Yes	String	The identifier of the location that is submitting inventory data. Note that this value should actually be the external ID for the location, not the name as stored in the Kibo Composable Commerce Platform admin.
PartNumber	Optional	String	A merchant-assigned part identification for the item.
UPC	Yes	String	The UPC for the item. This should be the most unique identifier for the item; any other identifier can be used in PartNumber.
SKU	Optional	String	The SKU for the item.
LotCode	Optional	String	The granular lot code for the item.
Date	Optional	String	The granular date for the item.
Condition	Optional	String	The granular condition for the item.
SerialNumber	Optional	String	The granular serial number for the item.
Quantity	Conditional	Integer	For Refresh imports: Conditionally required — see Quantity: Conditional Requirement for Refresh Imports below. For Update imports: Always required. This value includes a + (plus) or – (minus) sign and is the change in quantity from the previous submission. Examples are +352 and -4. By default, this value is used for the On Hand inventory level and the system calculates the appropriate Available amount. If you want this quantity to be applied directly as the Available inventory instead, contact Kibo Support to change its behavior in your tenant configurations.
Bin	Optional	Integer	The name of the bin within a location. Used for warehouse and store management. It must exist for the LocationCode.
LTD	Optional	Integer	Custom field used for store prioritization. Kibo will advise you on the type of data to enter in this field if you need to use it.
SafetyStock	Optional	Integer	Quantity of this item you want to keep in stock to ensure your stock isn’t completely depleted. Both Safety Stock and Floor are optional; most people prefer Safety Stock to Floor.
Floor	Optional	Integer	Absolute minimum quantity of this item that should be in stock at any time. Both Safety Stock and Floor are optional; the two values are used for similar purposes; most people prefer to use Safety Stock rather than Floor.
ExcessInventoryThreshold	Optional	Integer	The maximum Available quantity you want to hold in stock. Any Available inventory above this threshold is considered Excess.
AssumeInfiniteInventory	Optional	Boolean	This flag when set to true signifies that the inventory record is to be considered as having unlimited stock for allocation, even when the available quantity is zero.
DeliveryDate (XML) / Delivery_Date (CSV)	Optional	String (date-time)	The expected delivery date for incoming future inventory records.
ExternalID (XML) / External_ID (CSV)	Optional	String	A unique external identifier used for future inventory.
CurrencyID	Optional	Integer	Field defining which currency is used to store the RetailPrice. Required if RetailPrice is passed in. See the Currency API for details.
RetailPrice	Optional	Decimal	The location specific price the product being refreshed. CurrencyID is required if RetailPrice is passed in.
Attributes	Optional	Array	A list of attributes that are assigned to the item.
InventoryLocatorName	Optional	String	An identifier to indicate where a particular SKU exists within a location. For example, “Aisle 5” would indicate that the bin this item belongs to is located in Aisle 5. The maximum length is 50.
Custom Tag	Optional	String	If you use tags for inventory segmentation, you can include those tags in the file just like any other field. The tag name should be the field name (such as “Channel”) and values should match the options set up in your segmentation configuration (such as “Amazon” or “eBay”).
<attributename>	Optional	String/Integer/Boolean/Date	Custom inventory extensible attributes defined at the product-location level. Replace `<attributename>` with the actual attribute code. Format varies by Input Type: String for text/list, Integer for numbers, Boolean for Yes/No, Date for dates. You can update these custom attributes without requiring a full inventory refresh.

Quantity — Conditional Requirement for Refresh Imports

The Quantity field is conditionally required for Refresh import rows. Whether it must be provided depends on the presence of other fields in the same row:

Condition	`Quantity` Required?	Behavior
No other dependent fields are present	Yes	A missing or null `Quantity` will cause a validation error for that row.
At least one dependent field is present	No	`Quantity` may be omitted. The existing on-hand quantity for that item is preserved. Only the provided dependent fields are updated.

Dependent fields — any one of the following makes Quantity optional:

Field Name	Notes
`LTD`	Long-term demand value
`Floor`	Absolute minimum stock threshold
`SafetyStock`	Buffer stock to keep reserved
`InventoryLocatorName`	Bin location description within the store
`ExcessInventoryThreshold`	Maximum available quantity before excess
`AssumeInfiniteInventory`	Treat item as unlimited stock for allocation
Extensible attributes	Any custom key-value attributes passed in the extensible attributes map

Validation Rules When Quantity Is Required

When Quantity is required (no dependent fields present), the following validation applies:

The value must be an integer.
By default, the value must be non-negative (≥ 0).
If your account has the Available Inventory Updates feature enabled, negative integers are permitted, allowing an explicit reduction of available stock below zero.

Behavior When Quantity Is Omitted

When Quantity is omitted and a dependent field is present:

The row is accepted without error.
The on-hand quantity for that item is not modified.
Only the fields explicitly provided in the row are updated on the record.

This allows a Refresh file to function as a targeted attribute update — for example, toggling AssumeInfiniteInventory across a set of items without resetting their physical stock counts.

Refresh Quantity Examples

Valid — Quantity omitted, dependent field present:

LocationCode,UPC,AssumeInfiniteInventory
STORE-001,012345678901,true

Accepted. AssumeInfiniteInventory is updated; existing on-hand quantity is unchanged. Valid — Quantity provided with dependent field:

LocationCode,UPC,Quantity,SafetyStock
STORE-001,012345678901,100,10

Accepted. Both Quantity and SafetyStock are updated. Invalid — No Quantity and no dependent fields:

LocationCode,UPC
STORE-001,012345678901

Rejected. Quantity is required when no dependent fields are present.

Examples

Here is an example import sequence:

Create the file : T_{tenantId}_REFRESH_130909121152.xml (or .csv)
Compress (zip) the file : T_{tenantId}_REFRESH_130909121152.zip
Upload the zip file.
Upload a Trigger/Control file : T_{tenantId}_REFRESH_130909121152.zip.done

XML File The following example provides inventory information for two locations and includes only required elements.

<?xml version="1.0" encoding="UTF-8"?>
<Inventory>
   <Location>
      <LocationCode>0001</LocationCode>
      <Item>
         <PartNumber>883360541099</PartNumber>
         <UPC>883360541099</UPC>
         <Quantity>11</Quantity>
         <SafetyStock>4</SafetyStock>
         <Floor>1</Floor>
         <LTD>3</LTD>
         <ExcessInventoryThreshold>2</ExcessInventoryThreshold>
         <AssumeInfiniteInventory>true</AssumeInfiniteInventory>
         <Attributes>RESTOCK-CARRIER|RESTOCK-TRUCK</Attributes>
         <InventoryLocatorName>Aisle 2</InventoryLocatorName>
         <Colors>Red|Blue|Green</Colors>
         <>
      </Item>
      <Item>
         <PartNumber>883360541075</PartNumber>
         <UPC>883360541075</UPC>
         <Quantity>44</Quantity>
         <SafetyStock />
         <Floor />
         <LTD />
         <ExcessInventoryThreshold />
         <AssumeInfiniteInventory />
         <Attributes>RESTOCK-CARRIER</Attributes>
         <InventoryLocatorName>Aisle 3</InventoryLocatorName>
         <Colors />
      </Item>
   </Location>
   <Location>
      <LocationCode>0002</LocationCode>
      <Item>
         <PartNumber>883360541099</PartNumber>
         <UPC>883360541099</UPC>
         <Quantity>11</Quantity>
         <SafetyStock>4</SafetyStock>
         <Floor>1</Floor>
         <LTD>3</LTD>
         <ExcessInventoryThreshold>2</ExcessInventoryThreshold>
         <AssumeInfiniteInventory>false</AssumeInfiniteInventory>
         <Attributes>RESTOCK-CARRIER</Attributes>
         <InventoryLocatorName>Aisle 4</InventoryLocatorName>
         <Colors>Red|Blue</Colors>
      </Item>
      <Item>
         <PartNumber>883360541075</PartNumber>
         <UPC>883360541075</UPC>
         <Quantity>44</Quantity>
         <SafetyStock>5</SafetyStock>
         <Floor>1</Floor>
         <LTD>2</LTD>
         <ExcessInventoryThreshold>2</ExcessInventoryThreshold>
         <AssumeInfiniteInventory>false</AssumeInfiniteInventory>
         <Attributes>RESTOCK-CARRIER</Attributes>
         <InventoryLocatorName>Aisle 5</InventoryLocatorName>
         <Clearance>true</Clearance>
      </Item>
   </Location>
</Inventory>

CSV File The following example provides inventory information for two locations. Note that CSV has some special requirements:

The header is optional.
Order of inventory fields matters: LocationCode,PartNumber,UPC,SKU,Quantity,Bin, etc.
At least the string fields must be quoted. Quotes may not be required for the data field names or integers, but if you experience errors then Kibo recommends adding quotes to all values as shown below.

"LocationCode","PartNumber","UPC","SKU","Quantity","Bin","LTD","SafetyStock","Floor","ExcessInventoryThreshold","AssumeInfiniteInventory","CurrencyID","RetailPrice","Attributes","InventoryLocatorName",Colors
"0001","PartNumber1","UPC1","SKU1","11","BinName1","1.0","2","4","2","True","","25.99","","Aisle 1","Red|Green|Blue"
"0001","PartNumber2","KCCP1","","44","BinName2","","Aisle 2","Red"
"0002","PartNumber1","UPC1","SKU1","11","","1.0","2","1","","Aisle 3"
"0002","PartNumber2","UPC1","","44","","Aisle 4"

CSV File with Inventory Tags This example includes a custom tag called “channel” used in inventory segmentation. This indicates that these inventory records belong to the Amazon order channel.

"LocationCode","PartNumber","UPC","SKU","Quantity","InventoryLocatorName","AssumeInfiniteInventory","Channel"
"0001","PartNumber1","UPC1","SKU1","11","Aisle 1","True","Amazon"
"0002","PartNumber2","UPC1","","44","Aisle 4","False","Amazon"

Catalog

Customers

B2B

Fulfillment

Inventory

Locations

Marketing

CMS

Orders

Publishing

Order Routing

Reporting

Search

Subscriptions

System

Call Center

Content

Import/Export

Agentic

Dropship

Types of Inventory Import

Refresh File Attributes

Update File Attributes

Getting Started

SFTP Best Practices

Create and Upload Inventory Files

Naming Inventory Import Files

Data Elements

Quantity — Conditional Requirement for Refresh Imports

Validation Rules When Quantity Is Required

Behavior When Quantity Is Omitted

Refresh Quantity Examples

Examples

​Types of Inventory Import

​Refresh File Attributes

​Update File Attributes

​Getting Started

​SFTP Best Practices

​Create and Upload Inventory Files

​Naming Inventory Import Files

​Data Elements

​Quantity — Conditional Requirement for Refresh Imports

Validation Rules When Quantity Is Required

Behavior When Quantity Is Omitted

Refresh Quantity Examples

​Examples

Types of Inventory Import

Refresh File Attributes

Update File Attributes

Getting Started

SFTP Best Practices

Create and Upload Inventory Files

Naming Inventory Import Files

Data Elements

Quantity — Conditional Requirement for Refresh Imports

Examples