Set Tags 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.

This guide also explains the allocation process for orders with inventory tags.

Before You Begin

Be aware of the following behavior:

  • If a trial product replaces the parent item in 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.

As well as the following reminders and validation rules:

  • Tags do not need to be specified, and you can choose which of the tags configured in your tenant that you want to specify. If you don't specify any tags or you only specify partial tags, then the default tags will be used for that item.
  • If an item has a tag name, then a tag value is also required.
  • You can only apply a tag name once per item (meaning that you cannot duplicate a tag with different values). For example, an item can have their Channel tag set to "Amazon" but you cannot also set Channel to "eBay".
  • An item can have multiple tags, but all names and value must be valid. For example, an item can have their Channel tag set to "Amazon" and their Customer Tier tag set to "Tier 1." 

Inventory tags are applied at the individual item level, so different items in an order 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. Once the order is submitted, you will no longer be able to edit the tags.

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). The line items section of an order with a callout for the Add/Edit Inventory Tags button
  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 by clicking Clear.The Add/Edit Inventory Tags pop-up with dropdown menus for three tags
  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"


When you submit an order with tags specified, then inventory will be allocated from those tags if it's available. If there's not enough inventory available for that tag, then the unavailable quantity will be handled according to your Order Routing after-actions. It will not be allocated from the default or any other tags.

If a tag name was not specified for an item, then the system will allocate it from the tag you configured as the default. If there isn't enough inventory in the default tag, then the remainder will either be assigned according to your Order Routing after-actions or pending items will be created.

For example, if an order item's Fulfillment Type tag is specified to be "STH" but the Channel tag is not specified, then it will be set to the default ("Kibo"). The system will then look for inventory in the STH-Kibo tag combination. If there is no inventory available, then the Order Routing after-actions or pending items will be invoked.