Catalog variant data and product groupings

This is for:

Developer

Depending on your use case, you may either want to group certain products together or use variants. This article explains the difference between the two and the expected outcome if you structure your catalog data via these mechanisms.

For more information on products and variants, see catalog object types.

To showcase a product and its variants together, you can represent each variant as an individual product and then use a field value shared by all these products to group them together. This is particularly useful in an ecommerce setting.

Product variants

In a catalog entity featuring items of the variant catalog object, customers are shown both displayable and sellable items.

Displayable items are of the product catalog object and are the ones that are displayed in search results or product listing pages (PLPs).

Sellable items are of the variant catalog object and are the ones that a customer will actually purchase.

Example

An online shoe store offers a product called Coveo Soccer Shoes - Red. These shoes are available in various sizes (6, 7, 8). Search results or PLPs showcase the Coveo Soccer Shoes - Red shoes, displaying the overall design and features, but if a user decides to make a purchase, they would need to specify the exact size they want, such as size US 7, making the US-7 variant a sellable version of the Coveo Soccer Shoes - Red product.

Therefore, each size of the Coveo Soccer Shoes - Red product is considered a sellable variant of that product.

Coveo variants are never returned as search results or shown on a PLP. A variant instead provides additional filtering to refine the search based on the variant information.

Important

Metadata keys defined in variants can be used for filtering with facets, but can’t be used for sorting results.

Let’s take a look at the following example where you have a Coveo Soccer Shoes - Red product and its two variants, Coveo Soccer Shoes - Red ; Size 8 and Coveo Soccer Shoes - Red ; Size 9. Notice that with variants, you can specify the sizes the shoes comes in.

The following is the JSON object you can use to identify the Coveo Soccer Shoes - Red product:

Note

In your Catalog source, some of the fields discussed here, such as ec_product_id and ec_variant_id, may have different labels. Their labels depend on your catalog configuration.

 
{
  "documentId": "product://001-red", 1
  "ec_name": "Coveo Soccer Shoes - Red",
  "ec_product_id": "001-red", 2
  "objecttype": "Product", 3
  "ec_images": ["https://myimagegallery?productid"], 4
}
1 The value of the documentId metadata is the unique identifier of your item in the index and will also serve as the item’s uri field value. This value must be a valid URL with a proper URI prefix, such as product://, or any other scheme that fits your catalog data. The URL format ensures that the documentId is recognized as a valid URI, which is essential for updating the item’s information in the index.
2 ec_product_id is the product’s unique identifier. All variants of this given product will share the same value for this field.
Note

To train Coveo Machine Learning (Coveo ML) models, this field can’t contain the # character.
3 The objecttype metadata plays a crucial role in identifying the various relations between the products and its variants.
4 The ec_images points to the display image of the given product.

The Coveo Soccer Shoes - Red ; Size 8 variant JSON looks like the following:

{
  "documentId": "variant://001-red-size-8",
  "ec_name": "Coveo Soccer Shoes - Red ; Size 8",
  "ec_product_id": "001-red", 1
  "objecttype": "Variant", 2
  "ec_variant_id": "001-red-size-8", 3
}
1 The ec_product_id of the variant is the same as the one given to the parent product.
2 The objecttype of a variant is given the value of Variant.
3 The ec_variant_id metadata distinguishes a given variant from others, as each variant has a unique ec_variant_id value.
Tip
Leading practice

To better identify to which product a variant belongs to, Coveo recommends using ec_product_id to form part of ec_variant_id. For example, in the previous code sample, you can see that ec_product_id is 001-red and ec_variant_id is 001-red-size-8. Doing so makes it easy to identify which product the variant is related to.

Similarly, here is the JSON of the Coveo Soccer Shoes - Red ; Size 9 variant:

{
  "documentId": "variant://001-red-size-9",
  "ec_name": "Coveo Soccer Shoes - Red ; Size 9",
  "ec_product_id": "001-red",
  "objecttype": "Variant",
  "ec_variant_id": "001-red-size-9",
}

Notice that the variant doesn’t include the product image ec_images because, in this scenario, the actual product, Coveo Soccer Shoes - Red, maintains the same appearance regardless of its size. This further emphasizes the essential distinction between products and variants, with variants never being returned by Coveo.

If we were selling the Coveo Soccer Shoes - Red product with both a size and a width attribute, we would need a distinct variant item for every possible combination of these attributes.

To a prospective customer, you might want to display only the product rather than a list all possible variants. If you choose to do this, you should provide a way of filtering the products using variant information. For example, you could include a facet displaying different shoe sizes. If a customer clicks a specific size, only products with available variants with the specified shoe size should be displayed. This is precisely the sort of mechanism that Coveo provides via product variants.

Important

  • Coveo Soccer Shoes - Red and Coveo Soccer Shoes - Blue can’t be considered variants since they’re not sellable items but rather displayable items. If you wish to avoid creating variants, you would have to create each possible sellable item as its separate product (for example, Coveo Soccer Shoes - Red; Size 8). This approach isn’t recommended as it would increase the number of items in your index and lead to performance issues.

  • As Coveo doesn’t return variants, visitors can’t perform free text searches specifically on the content of items defined as variants, including the ec_variant_id. Consequently, if a user searches for "Size 8 shoes," the variant Coveo Soccer Shoes - Red; Size 8 won’t be returned in the search results.
Tip
Leading practice

In your catalog content, avoid using the same field name that you intend to use as facets, on different types of items. For example, if you’re defining the color at a product level, then you shouldn’t define the color at the variant level. If you need to include a field at both levels, prefix it with product and variant (e.g, productcolor, variantcolor) so that they’re different in the index.

Variants for products that have no variations

If your catalog configuration contains variants, it’s essential to ensure that all products have at least one associated variant, even if the product itself doesn’t come in different variations.

This means that, in cases where a product has no variations, you must create an item of the variant object type for that product. That variant item must contain the following metadata keys:

  • A documentId to uniquely identify the item in the index. This value must be a valid URL with a proper URI prefix, such as product://, or any other scheme that fits your catalog’s configuration.

  • An ec_product_id, which identifies the product the variant belongs to. It should be the same value as the ec_product_id used in the related product item.

  • An ec_variant_id for which the value must correspond to both the product and variant’s ec_product_id.

  • An objecttype for which the value is variant.

Making a variant with only these metadata keys is necessary as any additional information could lead to the variant appearing as a filtering option for the product it’s related to.

For example, consider the following product that doesn’t come in any variations:

{
  "documentId": "product://001",
  "ec_name": "Coveo Coffee Mug",
  "ec_product_id": "001",
  "objecttype": "Product",
  "ec_images": ["https://myimagegallery?productid"],
}

In addition to your product, you would have to create the following variant:

{
  "documentId": "variant://001",
  "ec_product_id": "001",
  "objecttype": "Variant",
  "ec_variant_id": "001", 1
}
1 When configuring a variant for a product that has no variations, the value of ec_variant_id metadata key must correspond to both the product and variant’s ec_product_id.

Product groupings

As mentioned before, the process of grouping displayable variations of a specific product is called product grouping.

For example, if a particular type of bicycle helmet comes in various colors, you could group the different colored helmets together to display a color swatch, as shown in this image:

Product grouping sample image

Returning to the original shoes example, suppose you don’t only have the Coveo Soccer Shoes - Red but also another color, such as blue (Coveo Soccer Shoes - Blue). You can group these products together so that customers can see what the different colors of the "Coveo Soccer Shoes" product look like. To achieve this, you need to ensure that both products share the same value for a specific grouping field that represents that they belong to the same group.

Tip
Leading practice

We recommend that you use ec_item_group_id commerce standard field as a grouping field with every product and populate it with a value. When a product isn’t part of a group, the ec_item_group_id field must be populated with the product’s own unique identifier (for example, ec_product_id).

Let’s take a look at the JSON representation of the Coveo Soccer Shoes - Red and Coveo Soccer Shoes - Blue items:

{
  "documentId": "product://001-red",
  "ec_name": "Coveo Soccer Shoes - Red",
  "ec_product_id": "001-red",
  "objecttype": "Product",
  "ec_images": ["https://myimagegallery?productid"],
  "ec_item_group_id": "001"
}
{
  "documentId": "product://001-blue",
  "ec_name": "Coveo Soccer Shoes - Blue",
  "ec_product_id": "001-blue",
  "objecttype": "Product",
  "ec_images": ["https://myimagegallery?productid"],
  "ec_item_group_id": "001"
}

As seen in this code sample, the ec_item_group_id is shared by all the products belonging to the same group. You don’t need to include this metadata key for variants.

Tip
Leading practice

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

  • ec_item_group_id: 001, ec_product_id: 001-red, ec_variant_id: 001-red-8_wide

  • ec_item_group_id: 026, ec_product_id: 026-blue_demo, ec_variant_id: 026-blue_demo-10_slim

To learn how to configure product groupings in the query pipeline, see Product grouping.

Note

Product groupings may affect query performance if many products share the same ec_item_group_id value. See limitations for more information.

Understanding the difference between variants and product groupings

At first glance, variants and product groupings may appear as similar ways of logically organizing related items. However, it’s crucial to understand the differences between these mechanisms to achieve the desired outcome.

A helpful analogy for understanding when to use product grouping versus variants is envisioning a display shelf in a store. If the goal is to showcase a specific product on the shelf (equivalent to having a product show up on a search results page), it should be treated as an individual product.

Let’s take the example of Coveo Soccer Shoes. If you visit a physical shoe store, you notice the shoes displayed in various colours like red, blue, and other options. Each color would be considered a separate product. However, the size variations wouldn’t be presented on the shelf but instead kept in the back store. These different sizes represent the variants of the product.

Now, consider selling a Coveo TV in two sizes: 40 and 55 inches. The decision to use variants or product grouping depends on the desired result.

If you choose to create variants, you would have a Coveo TV product with Coveo TV: 40 inches and Coveo TV: 55 inches variants. Only Coveo TV would be displayed on search results and product listings pages. Variants can be used for filtering, allowing users to narrow down their search using facets. Additionally, since Coveo only returns products, using variants can lead to faster search results due to a lower number of items being returned.

However, a better approach might be to opt instead to create two different products, namely Coveo TV: 40 inches and Coveo TV: 55 inches, and use the product grouping method. Both products can be displayed in the results, as shown in the example of the bike helmet image mentioned earlier. The reason for opting for grouping in this scenario may be because, for TVs, you would want to prominently display and emphasize the different TV sizes since they have distinct characteristics, aesthetics, and pricing. This is best achieved by treating each TV size as a separate product rather than a variant.

Another advantage of using grouped items is the ability to perform free text searches, as both TV items are products returned by the Search API i.e if a user searches for "40 inch TV," the Coveo TV: 40 inches product will be returned in the search results.

In summary, the choice between variants and product groupings depends on the desired outcome and considerations such as filtering, search performance, and the specific use case.