Catalog variant data

Ecommerce Developer Product Documentation

In a catalog with variants, users search for products, and then select a variant to purchase. Variants are never returned as search results. A variant instead provides additional metadata on a parent product.

In this JSON example of a variant, the Coveo Soccer Shoes product varies in size and width, so a distinct variant would be needed for every possible combination of those.

 {
   "DocumentId": "variant://001-red-8_wide",
   "FileExtension": ".html",
   "ec_name": "Coveo Soccer Shoes - Red / Size 8 - Wide",
   "sku": "001-red-8_wide", 1
   "productsize": "8",
   "width": "wide",
   "productid": "001-red", 2
   "objecttype": "Variant" 3
 }

The above JSON contains information specific to a product for sale (or SKU).

Tip
Leading practice

We recommend using a simple method to differentiate the metadata. You can use dashes (-) as a separator between the groupid, product descriptor(s), and variant descriptor(s). You can also use underscores (_) as a substitute for spaces in descriptors, for example:

  • groupid: 001, productid: 001-red, sku: 001-red-8_wide

  • groupid: 026, productid: 026-blue_demo, sku: 026-blue_demo-10_slim

Observe that the product image ec_images isn’t included in the variant, since in this case, the actual Coveo Soccer Shoes - Red product looks the same regardless of its size and width.

1 The sku metadata is the unique identifier used to create a relationship with availability objects. In your catalog this metadata may have a different label. Use values that are standardized throughout your index.
2 The productid metadata is used to establish a relationship with the parent product. In your catalog this metadata may have a different label.
3 The objecttype metadata is crucial, as it will be used to identify the item as a variant in the index.
Important

When your catalog structure contains large amounts of items and requires availability channels, use the same field name (i.e. availableskus) on both the variant objecttype

{
  "DocumentId": "variant://001-red-8_wide",
  "FileExtension": ".html",
  "ec_name": "Coveo Soccer Shoes - Red / Size 8 - Wide",
  "sku": "001-red-8_wide",
  "availableskus": ["001-red-8_wide"],
  "productsize": "8",
  "width": "wide",
  "productid": "001-red",
  "objecttype": "Variant"
}

and availability channel objecttype written in an array.

{
  "DocumentId": "store://montreal",
  "FileExtension": ".html",
  "ec_name": "Montreal Store",
  "availableskus": ["001-red-8_wide", "001-red-7-narrow", "..."],
  "objecttype": "Availability"
}

This will improve the performance of your index.

Create additional variant fields

Sources using Coveo’s native connectors come with a set of default system fields. If you need to create more fields, see Create additional commerce fields.

Stream your catalog data to your source

You must then stream your catalog data to your source.

Review and inspect your indexed products

The Content Browser (platform-ca | platform-eu | platform-au) is a basic Coveo demo search interface to help you navigate and inspect the content of your Coveo organization sources.

For instructions on accessing the Content Browser and making use of its many features, see Inspect items with the Content Browser.