---
title: Catalog variant data and product groupings
slug: m53g0506
canonical_url: https://docs.coveo.com/en/m53g0506/
collection: coveo-for-commerce
source_format: adoc
---
# Catalog variant data and product groupings

Depending on your use case, you may either want to group certain products together or use [variants](https://docs.coveo.com/en/mc7f0326/).
This article explains the difference between the two and the expected outcome if you structure your [catalog data](https://docs.coveo.com/en/obcf0333/) via these mechanisms.

For more information on products and variants, see [catalog object types](https://docs.coveo.com/en/n8of5561/).

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](https://docs.coveo.com/en/3143/) featuring [items](https://docs.coveo.com/en/pa8f6515/) of the variant [catalog object](https://docs.coveo.com/en/ncig0154/), customers are shown both _displayable_ and _sellable_ items.

_Displayable_ items are of the [product](https://docs.coveo.com/en/m53g7119/) catalog object and are the ones that are displayed in search results or [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).

_Sellable_ items are of the [variant](https://docs.coveo.com/en/m53g7119/) 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](https://docs.coveo.com/en/198/), 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](https://docs.coveo.com/en/3139#catalog-configuration).

```json
{
  "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](https://docs.coveo.com/en/218/) is the unique identifier of your item in the [index](https://docs.coveo.com/en/204/) 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](https://docs.coveo.com/en/obcf0333/).
The URL format ensures that the `documentId` is recognized as a valid URI, which is essential for [updating](https://docs.coveo.com/en/p4eb0515/) 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)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/), 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:

```json
{
  "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.

> **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:

```json
{
  "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](https://docs.coveo.com/en/198/) 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.

> **Leading practice**
>
> In your catalog content, avoid using the same field name that you intend to use as [facets](https://docs.coveo.com/en/198/), 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 must 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](https://docs.coveo.com/en/3139#catalog-configuration) contains [variants](https://docs.coveo.com/en/mc7f0326/), 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:

```json
{
  "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:

```json
{
  "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](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/l78i2152_images/commerce-product-grouping-sample.png)

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, ensure that both products share the same value for a specific grouping [field](https://docs.coveo.com/en/200/) that represents that they belong to the same group.

> **Leading practice**
>
> Use the [`ec_item_group_id`](https://docs.coveo.com/en/n73f0502#standard-commerce-fields) 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:

```json
{
  "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"
}
```

```json
{
  "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.

> **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 descriptors, and variant descriptors.
> 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](https://docs.coveo.com/en/l78i2152/).

> **Note**
>
> Product groupings may affect query performance if many products share the same `ec_item_group_id` value.
> See [limitations](https://docs.coveo.com/en/l78i2152#limitations) for more information.

## Variants versus 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.