Variants

Apparel, Variants, or Models (Color, Size, and Variants)

Capabilities for model Items and their variants are described in detail here.

Fashion, shoes, sporting goods, and fragrances often require more complex item structures. Below are recommended properties to support these needs.

Create a Model Item

Property	Member of	Description
`id`	Item	Unique internal ID for the Item. Should be stable and not tied to GTIN/barcode.
`businessUnitGroupId` or `businessUnitId`	Item	The Business Unit or Group for this item. See Business Units.
`itemCategoryId`	Item	The Item Category ID. See Item Category.
`description`	Item	Textual description.
`name`	Item	Name used in receipts, search, and lists.
`status`	Item	Operational status. Set to Active for general use. See Item Statuses.
`type`	Item	Must be `MODEL` for the master Item. See Item Types.
`color`	AdditionalProperty	Color of the variant. Each unique value creates a color variant for filtering.
`size`	AdditionalProperty	Size of the item (numeric or text). Each unique value creates a size variant for filtering.
`style`	AdditionalProperty	Classifies products that share characteristics not varying by GTIN.
`brand`	Item	Brand name.

Create a Variant Item

Property	Member of	Description
`id`	Item	Unique internal ID for the Item.
`businessUnitGroupId` or `businessUnitId`	Item	The Business Unit or Group for this item.
`itemCategoryId`	Item	The Item Category ID.
`description`	Item	Textual description.
`name`	Item	Name used in receipts, search, and lists.
`status`	Item	Operational status. Set to Active for general use.
`type`	Item	Must be STOCK for sellable variants.
`color`	AdditionalProperty	Color of the variant.
`size`	AdditionalProperty	Size of the item.
`style`	AdditionalProperty	Classifies products that share characteristics not varying by GTIN.
`brand`	Item	Brand name.

Retailers may extend Items with properties like Season or Age. These can be applied to both Model and Variant Items.

Additional Properties

Property	Member of	Description
`SeasonName`	AdditionalProperty	Name of the season (e.g., "Winter").
`SeasonCode`	AdditionalProperty	Code for the season (e.g., WINTER, SPRING).
`SeasonYear`	AdditionalProperty	Year of the season (e.g., 2024).
`SportingActivityType`	AdditionalProperty	Activity type (e.g., FOOTBALL, RUNNING).
`TargetGender`	AdditionalProperty	Target consumer gender (e.g., MALE).
`TargetConsumerAge`	AdditionalProperty	Target age range.
`ItemVariantCategoryType`	AdditionalProperty	Category of Model Item (e.g., SHIRT, JACKET).

To link Items as variants of the same model, use the Item Link entity as described below.

A Model links SKU items (variants) to a model item, typically for color, size, or style.

This allows each variant to have its own barcode, stock level, and pricing, while being grouped under a model for search and promotions.

Item Link definition for a Model Item

Property	Member of	Data type	Description
`id`	ItemLink	string	Unique ID for the ItemLink.
`businessUnitId` or `businessUnitGroupId`	ItemLink	string	The Business Unit or Group for this association.
`name`	ItemLink	string	Name of the ItemLink.
`description`	ItemLink	string	Description of this ItemLink.
`status`	ItemLink	enum	Status of the ItemLink.
`itemId`	ItemLink	string	ID of the parent (model) Item (`MODEL` type).
`linkedItemIds`	ItemLink	string[]	Array of Item IDs for all StockItems that are variants of this Model.
`type`	ItemLink	string	Must be Model for model definitions.

This approach enables: