Skip to content

Load Items

In VibeIQ, item data spans three levels that can all be loaded in a single load process:

  • Item: Global data that exists outside the context of any project. Items can belong to families with options (e.g., Product/Colorway).
  • ProjectItem: Seasonal or project-specific data for an item within a project. The same item can have different project-level properties across seasons.
  • AssortmentItem: Data specific to an item within an assortment and project. An item can exist in many assortments within a single project (e.g., regional assortments).

Despite this hierarchy (Item > ProjectItem > AssortmentItem), the load file remains a flat CSV. A single property key should not be shared across more than one of these three entities, so properties are routed to the correct level automatically.

The Family/Option Model

Items in VibeIQ follow a Family/Option hierarchy:

  • A Family represents a product style (e.g., "Classic Tee"). It has a itemFamilyFederatedId and a name.
  • An Option represents a variation of that family (e.g., "Classic Tee - Red"). It has an itemOptionFederatedId and an optionName.

In your CSV, each row typically represents one option. Multiple rows can share the same itemFamilyFederatedId to create options under the same family. Properties set on the family level are shared across all options in that family.

Required Properties

In your load file, you must provide the following properties for each row. These may be the CSV column headers or usage of federatedMappings or conditionalColumns in the loader configuration to match these keys.

typePath is required for all item loads

Every item load requires typePath to be set to "item" or "item:<subtype>" (e.g., item:product:apparel). The simplest approach is a conditional column: 

{ "toProperty": "typePath", "default": "item:product:apparel" }
The load will fail if typePath is missing or doesn't match the required format.

Loading an Item Option for a Family

  • itemFamilyFederatedId: The federatedId of the Item Option's Family Item.
  • name: The name of the Item Option's Family Item.
  • itemOptionFederatedId: The federatedId of the Item Option.
  • optionName: The name of the Item Option itself.

Upon load, the loader will search for an Item Option by itemOptionFederatedId. If one does not exist, a new Item will be created and assigned to the Item Family that has federatedId of itemFamilyFederatedId. If that Item Family does not exist, it will be created as well.

name and optionName will be updated on the Family and Option Items, respectively, if they already exist. Therefore, it's critical that name and optionName remain consistent across subsequent loads of the same Items.

loadType:
- ITEM
federatedMappings:
  itemFamilyFederatedId: 'style'
  itemOptionFederatedId: 'colorName'
  name: 'styleName'
  optionName: colorName
conditionalColumns:
- default: item:product:apparel
  toProperty: typePath
- default: color
  toProperty: optionGroup

{
  "loadType": ["ITEM"],
  "federatedMappings": {
    "itemFamilyFederatedId": "style",
    "itemOptionFederatedId": "colorName",
    "name": "styleName",
    "optionName": "colorName"
  },
  "conditionalColumns": [
    {
      "default": "item:product:apparel",
      "toProperty": "typePath"
    },
    {
      "default": "color",
      "toProperty": "optionGroup"
    }
  ]
}

Loading Only an Item Family

  • itemFamilyFederatedId: The federatedId of the Item Option's Family Item.
  • name: The name of the Item Option's Family Item.

Upon load, the loader will search for an Item Family by itemFamilyFederatedId. If one does not exist, a new Item will be created.

name will be updated on the Family Item if it already exists. Therefore, it's critical that name remains consistent across subsequent loads of the same Items.

loadType:
  - ITEM
federatedMappings:
  itemFamilyFederatedId: 'style'
  name: 'styleName'
conditionalColumns:
  - default: item:product:apparel
    toProperty: typePath
  - default: color
    toProperty: optionGroup

{
  "loadType": ["ITEM"],
  "federatedMappings": {
    "itemFamilyFederatedId": "style",
    "name": "styleName"
  },
  "conditionalColumns": [
    {
      "default": "item:product:apparel",
      "toProperty": "typePath"
    },
    {
      "default": "color",
      "toProperty": "optionGroup"
    }
  ]
}

Combining Load Types

A single load process can handle all three entity levels by adding PROJECT_ITEM and/or ASSORTMENT to the loadType array:

  • Add PROJECT_ITEM to assign items to a project and set seasonal properties. See Project Items.
  • Add ASSORTMENT to assign items to assortments within a project. See Assortments.
{
  "loadType": ["ITEM", "PROJECT_ITEM", "ASSORTMENT"]
}

For the full configuration reference, see Loader Configuration Reference.