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.

For information about making Inventory API calls with granular fields, refer to the Inventory API Overview.

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. If a item with a condition is substituted, then substitute items will only be available if they have inventory with the same condition. 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. A record with a serial number can only have an inventory quantity of 1 and 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 or Delete to modify granular On Hand quantity. This will update the On Hand total at the UPC-Location level. Note that deleting the UPC-Location inventory item will remove all granular records associated with it.

Fulfiller UI

Granular fields will be displayed in Fulfiller UI shipment details under the Product Identifiers column. 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). 

If there are additional fields present, then the identifiers will include a link. Click this to open a pop-up with more details:

During the Validate Stock step, the values in this pop-up will be editable. This allows you to adjust the quantity for items being fulfilled from each granular record (between 0 and the total shipment quantity). If you want to fulfill some quantity from a different record than what's currently set, reduce the current quantity and click Add New Allocation in the bottom left. This adds a new row to the table for you to enter the appropriate values. The Add link will disappear if the sum of the current granular quantity matches the total shipment quantity.