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. Be aware that when setting Safety Stock at the granular level, the value will be applied to all inventory records associated with that UPC-Location.

{
    "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 available granular fields will be included underneath the UPC-Location record where you can enter optional values as desired. If you have defined specific conditions in your inventory settings, then a dropdown menu will be displayed for Condition instead of a text field. 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.

Available Inventory Counts

You can use granular Date and Condition fields to adjust how the Available inventory count is calculated and reflect more accurate Available-to-Sell (ATS) and Available-to-Promise (ATP) levels. This enables you to provide more accurate availability information and informed sales decisions, as you can display more finely-tuned inventory counts on your storefront.

• ATS: The amount of inventory that is immediately available to sell. This is determined by filtering current inventory counts based on the item conditions and/or expiration dates that you set up.
• ATP: The amount of inventory that can be promised for later delivery. This is determined by filtering current and future inventory counts based on the item conditions and/or expiration dates that you set up.

ATS and ATP are not returned as their own fields in KCCP. Once item condition and/or expiration rules have been set up, then you can filter the Inventory UI and APIs by those constraints to modify how the Available count is calculated and thus determine ATS and ATP as best fits your business needs. Inventory will also be allocated from the modified Available levels as appropriate.

Enable Inventory Expiration

If you want to use an item's granular Date field as its expiration date and use that to determine Available counts, contact Kibo Support to enable this behavior in your tenant attributes. If it has been enabled and the Date field is present, then expired inventory (where the Date is earlier than or equal to the current date) will not be included in Available counts and therefore cannot be allocated to.  

Configure Condition Rules

In order to configure the possible conditions and whether or not to include them in Available counts in your inventory settings, you must have Kibo Support enable this feature in your tenant attributes. If not enabled, the below table will not appear in your inventory settings.

1. Go to Main > Orders > Inventory > Inventory Settings.
2. In the Condition Availability section, click Add Condition. This will add an editable row to the table.
3. Enter a Condition name.
4. Toggle whether or not to Include in Available inventory counts. For example, you may want to exclude Damaged and Defective conditions while including New and Refurbished conditions. 
5. Click Save. 
6. To remove a condition, expand the actions menu on the far right of the row and click Delete. You should ensure that this condition has no allocated inventory before deleting it, meaning you may need to fulfill any allocated inventory and remove inventory records associated with it.

API Configuration

If you want to configure conditions via API instead, make a POST call to the .../inventory-management/v1/conditionavailability endpoint and a request body following the template below. This will set the given condition as a possible value, indicate whether it should be included in Available counts, and return a numeric ID in the response. 

{
    "condition": "string",
    "includeInAvailability": boolean
}

You can also upsert a condition using the POST call and including the numeric id field, retrieve all condition settings with a GET call to the same endpoint, and remove a condition by calling DELETE .../v1/conditionavailability/{ID}.

Filter in Inventory UI

Once their respective settings have been set up, the Inventory UI will display checkboxes for Exclude Expired Products and/or Include Condition Availability in the top right. Toggle them as needed to filter inventory records and calculate Available counts based on their expiration status and/or conditions. 

Display on Storefront

To display ATS and ATP counts on your storefront, include "enforceConditionAvailibility": true and/or "excludeExpiredInventory": true in the request when calling any of the below Real-Time Inventory Service APIs. This will filter the returned Available counts by the valid condition(s) or expiration status that you set up. Generally, determine ATS by retrieving current inventory and determine ATP by retrieving the combination of current and future inventory.

• Get Product Site Availability
• Get Group Site Availability
• Get Product Availability at Locations
• Get Group Availability at Locations

Those parameters can also be used to filter inventory search results from the Get Inventory and Get Inventory Aggregate calls. The linked API schemas will be updated soon.