Granular Inventory Fields

While the default way to differentiate inventory levels is by UPC-Location (meaning the UPCs that are present at a specific location), you can use granular fields for more detailed tracking instead. They can also be used in combination with External IDs on future inventory.

Types of Granular Fields

The following fields are available for granular inventory.

• SKU: As a UPC may be associated with multiple SKUs, this field differentiates inventory for each individual SKU and allows an aggregate amount to be displayed at the UPC level. 
• Lot Code: Tracking which lot a product is manufactured in may be helpful with product recalls, or tracking SKU inventory in different lots. There is a limit of 50 characters.
• Date: A manufacturing or expiration date (MM/DD/YYYY format) can improve your stock management by ensuring older products are used first. By default, inventory will be allocated from items with the earliest date after a location has been assigned.
• Condition: You may offer different conditions for the same UPCs, such as New or Refurbished for a couch. If a condition is specified for an item, then it will only be allocated from the inventory record that matches that condition. Items with conditions cannot be substituted. There is a limit of 50 characters.
• Serial Number: This is the lowest granular identifier for a physical piece of inventory, such as a laptop. Items with serial numbers cannot be substituted. There is a limit of 30 characters.

Enable Granular Fields

These additional identifiers must be enabled on your tenant by Kibo before you can use them. Please submit a request to Kibo Support to have this feature turned on for you.

Set Fields on Inventory Records

You can set granular quantities on inventory records via the Inventory API or the Inventory UI.

Inventory API Configuration

Provide the appropriate fields at the item level of the Refresh and Adjust Inventory API calls, such as in the below example that includes a SKU, serial number, and condition.

{
    "locationCode": "Example",
    "items": [
        {
            "partNumber": null,
            "upc": "PRODUCT_123",
            "sku": null,
            "ltd": 0,
            "floor": 0,
            "quantity": 4,
            "safetyStock": 0,
            "retailPrice": 1.99,
            "currencyID": 1,
            "serialNumber": "PRODUCT_123", 
            "lotCode": "PRODUCT_123",  
            "date": "2025-07-30T09:15:30-05:00",  
            "condition": "PRODUCT_123_CONDITION_1" 
        }
    ]
}

Admin UI Configuration

When creating a new inventory record, columns for enabled granular fields will be available underneath the UPC-Location record. Enter values into these optional fields as desired. You can add up to a maximum of 10 granular inventory records at once.

View/Edit Granular Fields

Granular inventory is displayed on both the Inventory and Fulfiller UIs.

Inventory UI

When any granular fields are present, current and future inventory records will be unique based on those values and additional columns will be displayed in the Inventory UI. The total On-Hand, Available, and Allocated quantities will be summed up at the UPC-Location level.

The below example shows several inventory records for the same product differentiated by lot code, date, serial number, and condition.

Expand the actions menu to the right and click Edit to modify granular On Hand quantity. This will update the On Hand total at the UPC-Location level. You cannot delete individual granular records, but deleting the UPC-Location inventory item will remove all granular records associated with it.

Fulfiller UI

Identifiers will also be displayed in Fulfiller UI shipment details. Line items will be separated by condition and serial number, meaning that if the customer purchases both a New and Used version of the same product then they will be displayed as two line items (shown below). 

Granular Fields in APIs

When performing the below API actions, use these fields to manage granular records. 

• Allocate Inventory and Create Order: You can specify condition and serialNumber fields at the item level.
• Deallocate Inventory: If you want to deallocate from a specific granular inventory record, include an inventoryID for each item on the item level. The inventoryIDs can be found in the shipment data.
• Fulfill Inventory: If you want to fulfill inventory from a specific granular record, include an inventoryID for each item on the item level. The inventoryIDs can be found in the shipment data.
• Update Inventory Allocation: Inventory allocation information is tracked at the item level of Shipment APIs, but sometimes discrepancies like damaged inventory or mismatched data may require reallocation. The .../commerce/shipments/{shipmentId}/items/{itemId}/updateInventoryAllocation API can be used to update the shipment item allocation data to adjust granular quantity and add new granular records. Details about this endpoint will be added to the API documentation soon.
  • Note that you cannot change the granular records of any item with a serial number, as these are always a unique item with an inventory of 1 and cannot be replaced.

Get Inventory Options

When calling Get Inventory, use the below flags to fine-tune which fields are returned in the results. The API documentation will be updated soon to add these fields to the model. 

• If showGranularInventory is not provided, the On Hand inventory calculation will include Safety Stock.
• If showGranularInventory is provided, then the response will include granular inventory records but exclude the granular-levels Safety Stock, LTD, and Floor values.
• If showGranularInventory and showExtraGranularProductFields are both provided, the response will display both granular inventory fields and the granular-level Safety Stock, LTD, and Floor values. However, Safety Stock will not be included in the calculation of On Hand inventory.

{
    "type": "ALL",
    "items": [
        {
            "upc": "upc-1",
            "sku": null
        }
    ],
    "pageNum": 1,
    "pageSize": 100,
    "showGranularInventory": true,
    "showExtraGranularProductFields": true
}