Catalog variant data and product groupings
Catalog variant data and product groupings
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 via these mechanisms.
Product variants
In a catalog featuring items of the variant object type, customers are shown both displayable and sellable items.
Displayable items are of the product object type and are the ones that are displayed in search results or Product Listing Pages (PLPs).
Sellable items are of the variant object type and are the ones that a customer will actually purchase.
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.
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 variants let you 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 |
{
"documentId": "product://001-red",
"ec_name": "Coveo Soccer Shoes - Red",
"productid": "001-red",
"objecttype": "Product",
"ec_images": ["https://myimagegallery?productid"],
}
The documentId metadata is the unique identifier of your item in the index and will be used to fill the item’s uri field.
This value is essential to update the item’s information. |
|
The productid is the product’s unique identifier.
All variants of this given product will share the same value for this field. |
|
The objecttype metadata plays a crucial role in identifying the various relations between the products and its variants. |
|
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",
"productid": "001-red",
"objecttype": "Variant",
"sku": "001-red-size-8",
}
The productid of the variant is the same as the one given to the parent product. |
|
The objecttype of a variant is given the value of Variant . |
|
The sku metadata distinguishes a given variant from another as each variant has a unique sku . |
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",
"productid": "001-red",
"objecttype": "Variant",
"sku": "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.
|
|
|
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 |
Variants for products that have no variations
If your catalog configuration contains variants, it’s essential to ensure that all products in that catalog have at least one associated variant, even if the product itself doesn’t come in different variations.
In cases where a product has no variations, you must create a variant with minimal information to prevent this variant from appearing as a filtering option for the attached product.
For example, consider the following product that doesn’t come in any variations:
{
"documentId": "product://001",
"ec_name": "Coveo Coffee Mug",
"productid": "001",
"objecttype": "Product",
"ec_images": ["https://myimagegallery?productid"],
}
In addition to your product, you would have to create the following variant:
{
"documentId": "variant://001",
"productid": "001",
"objecttype": "Variant",
"sku": "001",
}
When configuring a variant for a product that has no variations, the value of sku must correspond to the product’s and variant’s productid . |
Product groupings
In an ecommerce interface, you often want to group similar products. 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 the image below.
The process of grouping displayable variations of a specific product is called product grouping.

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.
|
Leading practice
We recommend that you use |
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",
"productid": "001-red",
"objecttype": "Product",
"ec_images": ["https://myimagegallery?productid"],
"ec_item_group_id": "001"
}
{
"documentId": "product://001-blue",
"ec_name": "Coveo Soccer Shoes - Blue",
"productid": "001-blue",
"objecttype": "Product",
"ec_images": ["https://myimagegallery?productid"],
"ec_item_group_id": "001"
}
As seen above, the ec_item_group_id
is shared by all the products belonging to the same group.
You don’t need to include this field for variants.
|
Leading practice
We recommend using a simple method to differentiate the metadata.
You can use dashes (
|
To learn how to configure product groupings in the query pipeline, see Product grouping.
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 would not 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.