Inventory Segmentation

Segmentation brings more flexibility to inventory management, allowing each inventory record to be separated into different tags to indicate that portions of its total quantity are intended for different channels, customer groups, fulfillment methods, or other needs. This allows for:

  • Setting a percentage of the quantity that would be available for each tag.
  • Setting discrete units at the location level as available for each tag.

Note that changes to these settings may not immediately take effect when processing orders. It may take up to 15 minutes for updates to be reflected in the system while the cache refreshes.

How Segmentation Works

During order routing and fulfillment, inventory will be allocated from the segment that each order item belongs to. When processing returns, inventory segments will also be checked so that returned items are restocked back to their original segment (if no segment is defined, then the items will be restocked to the location selected by the customer service representative). This helps accurately track inventory levels and make sure that items are fulfilled from the proper channel.

See the Inventory API documentation for information about how to assign segments to inventory records from the API instead of user interface, as well as how to assign order items to inventory segments when placing an order.


Segmentation is determined with tags, which identify the groups that inventory must be split into. For example, tags could define how much of each inventory record is set aside for a certain sales channel: the Kibo storefront, Walmart, or Amazon. The percentages of the inventory allotted for each channel would add up to 100% - the Kibo storefront could have 80% of the inventory, Amazon 10%, and Walmart 10%.

This means that the quantities for each tag will never exceed the total quantity of inventory for that product at the location. For a visual representation, see the below example. This inventory (the quantity of Product BC76845 at the location Retailer2) is categorized based on a combination of channel and order type tags. The discrete On Hand, Available, and Allocated values for each tag can be added up to equal the overall On Hand, Available, and Allocated quantities.

Inventory segmentation tags on an example product

Enable Inventory Tags

Tags must be enabled and configured before inventory can be used in segments.

  1. Click Inventory Settings in the Inventory UI to access the inventory configurations.

    The Inventory navigation menu

  2. Under the Inventory Tags section, click Enable Inventory Tags to toggle this functionality on.

    Callout of the Enable Inventory Tags button of inventory settings

This will create an empty table where tags will be displayed once created.

The empty table created by enabling tags

Create Inventory Tags

To begin configuring your first tag, click Create Inventory Tag. A pop-up will appear with the configuration settings.

  1. Give the tag a name (such as Channel).
  2. Enter the value option (such as Amazon).
  3. At least one value must be set – this first value will always be the default. A default is required, as if no tag is specified for an inventory item then it will use this value instead.
  4. If desired, set the allocation percentage. This will determine how much of the total inventory is made available for this segment. In this example, 50% of the discrete total inventory will always be allocated for the Amazon sales channel.

    If you want to use discrete values for your inventory segmentation instead of a percentage, you must leave the Inventory Allocation % field blank. If you do set percentage values but want to switch to discrete values later, you must delete all tags and re-add them without percentages to view discrete inventory.

  5. Once the initial default is set, click Add Tag Value to create another option for this tag. These values should be unique within each tag name.The Create Tag Name module with name, value, and allocation percentage options
  6. If an allocation percentage is specified for each value, then all of the percentages must add up to 100%. 
    • In the below example, the first value is allocated at 50% so additional tags could be created with allocations of 20% and 30%. However, it is not required to set these percentages – if any are left blank, then validation will not be done for that tag value when inventory levels are refreshed. It will effectively accept any amount of inventory, as long as other values' percentage requirements are satisfied first.Example of the Create Tag Name module with additional tag values being added
  7. Once set, the new tag is added to the Inventory Tags table. Additional tags with their own set of possible values can be added, though each tag name should be unique.
  8. Click a tag in the table to expand its details and view the possible values and allocation percentages, as well as change the preferred default value. Or, use the dropdown menu to Edit or Delete a tag. Editing will open the same pop-up as used for creation, allowing you to alter all values and delete any non-default values.Example of a populated Inventory Tags table in inventory settings

Apply Tags to Inventory Records

If tags have been enabled, then every single inventory record will be associated with those tags. However, items do not need to have tags specified in the order data. If an item is without a tag name and associated value, then the system will use the default. If an item does have a tag name provided in the order, then an associated value must be included as well.

For example, if your configuration has the tags OrderType and Channel and you only care about a certain order item's OrderType, then do not include the Channel tag in the order data and it will be set to the default. If neither of these tags matter for a product, then do not name either of them in the order data.

Set Tags via API

An example of an Inventory Refresh call that sets inventory data with discrete tag values:

  "locationCode": "examplelocation",
  "items": [
      "upc": "AD1001",
      "quantity": 100,
      "tags": {
        "Channel": "Warehouse"
      "upc": "AD1001",
      "quantity": 50,
      "tags": {
        "Channel": "Target"

Upload Tagged Inventory Files

The inventory import process also supports segmentation, so you can use this file upload to apply your tags instead of doing it via API. To do this, add the tag name as a column header after the default headers and insert the tag value into the column value. The example below shows a sample file with Channel and OrderType tag columns:


Allocate Inventory in Orders

Once inventory is tagged, you should indicate which segment to allocate from when placing orders. This can be done in the storefront cart and checkout, the Upsert Inventory Tags API, the Admin UI when creating offline orders, and directly through the Create Order API.

Be aware of the following behavior:

  • If a trial product replaces the parent item as for subscriptions, then the trial product will not have tags and you will have to re-add them.
  • If an item is split such as for a BOGO discount, tags will be copied on the split item and will still be editable.
  • If there are more than three tags in a Pending order, then only the first three will be displayed and editable. However, the full list of tags will be visible from the Order Details tab.
  • You can only apply a tag name once per item (meaning that you cannot duplicate a tag with different values). A value is required for every given name.

Inventory tags are applied at the individual item level, so different items can use different tag values even for the same tag. For instance, if you have a tag for "Condition" then you can have one item in the order with the "New" value and another item with the "Used" value.

Cart and Checkout

The Add Item to Cart API and Add Checkout Item API support tag names and values in the item-level data, allowing inventory segments to be set or updated in your storefront cart and checkout prior to submitting the order. 

Note that if an item is fully or partially out of stock, then a warning message will be shown to state that it is out of stock. If backordering is enabled for the item(s), then the message will instead indicate that the item will be backordered.

Upsert Inventory Tags API

If an order is in Pending status, the Upsert Inventory Tags API will also allow you to edit these tags instead of doing it through the cart or checkout. Once the order is submitted, you will no longer be able to edit the tags.

The schema for this endpoint will be added to the API documentation soon, and linked here when available.

Offline Order Creation

When adding an item to a new order in the Admin UI:

  1. Click Add Inventory Tags (if no tags have yet been added to the item yet) or Add/Edit Inventory Tags (if there are tags set on the item). 
  2. In the pop-up, select names and values to add up to three new tags. Any tags already added to the item will be prepopulated, which you can change the value of or remove with the Clear button.
  3. Click Confirm.

Create Order API

When you submit an order through the Create Order API,  if there is no inventory available for a particular tag value (such as Target) and an order attempts to allocate an item from that tag, then the order item will not be allocated to the default tag. In that case, units that are not available will be handled by your Order Routing after-actions instead.

The below example is an excerpt of the items object from a Create Order call allocating items to the Target tag:

"items": [
            "fulfillmentLocationCode": "examplelocation",
            "fulfillmentMethod": "Ship",
            "lineId": 1,
            "product": {
                "price": {
                    "price": 40
                "productCode": "AD1001",
                "name": "Treven Getta Patent Pump"
            "quantity": 2,
            "total": 40,
            "inventoryTags": [
                    "name": "Channel",
                    "value": "Target"

View Segments and Update Order Items

Segmented inventory is displayed in the Inventory UI and Inventory API data, and you can manage the inventory tags of individual order items from the Orders UI.

Inventory UI

Expanding a row will reveal its tags and the portions of the total quantities that has been set for each segment of tag values. As shown earlier, the On Hand, Available, and Allocated values add up to the total quantity for the inventory record.

If inventory is out of stock (in other words, if the available inventory is 0) at a particular location, then its row will be highlighted red. If available inventory is less than the safety stock but is not yet 0, then it will be highlighted yellow to warn that it will be going out of stock soon.

The safety stock is set at the overall record level, and all segments within that record are compared against that value. If only one segment is out of stock or its available quantity is below the safety stock value, then only that row will be highlighted.

Example of a product highlighted in red where quantity is 0

API Responses

You can also view tagged inventory segments when retrieving inventory data from the API, such as in this example response:

        "locationName": "Main Warehouse",
        "locationCode": "homebase",
        "tenantID": 31545,
        "onHand": 150,
        "available": 148,
        "allocated": 2,
        "pending": 0,
        "upc": "AD1001",
        "blockAssignment": false,
        "ltd": 0,
        "floor": 0,
        "safetyStock": 0,
        "distance": 0,
        "directShip": true,
        "transferEnabled": true,
        "pickup": true,
        "countryCode": "US",
        "taggedInventory": [
                "onHand": 100,
                "available": 100,
                "allocated": 0,
                "pending": 0,
                "tags": {
                    "Channel": "Warehouse"
                "futureInventory": null
                "onHand": 50,
                "available": 48,
                "allocated": 2,
                "pending": 0,
                "tags": {
                    "Channel": "Target"
                "futureInventory": null

Orders UI

You can access the inventory tags on order items in the Orders UI.

You can only edit tags on Pending orders. You cannot edit tags on orders that have been submitted, only view them.

To view the tags:

  1. Go to Main > Orders > Orders.
  2. Click on an order to view its details.
  3. Click View # Inventory tags under a line item.
  4. In the pop-up, the current tags and values will be displayed. If the order is in Pending status, then a message will direct you to edit the tags via the Edit Details button:If the order has been submitted, then the message will instead inform you that you cannot modify the tags:

If the order is Pending,  return to the order details to edit the tags: 

  1. Click Edit Details on the order, where you will be able to edit and add order items.
  2. Click the Add/Edit Inventory Tags link underneath a line item. 
  3. A pop-up with the editable tags will appear, displaying the first three tags on the item. Select new names/values or add new tags as necessary. Remove tags with the Clear button.
  4. Click Confirm.

When creating a new shipment for an existing order, you will be able to add inventory tags to the items in the new shipment. This process will be the same as when creating tags on a new order.