What are the possible variants configuration options & display capacities ?

1. Fundamental Concepts

1.1 Definition of an item

In the catalog feed, each line (CSV) or each <item> (in XML) represents an item (SKU).

A product with variations (e.g., a T‑shirt with multiple sizes/colors) will therefore result in several items in the catalog feed.

Example:

A T‑shirt available in 3 sizes (S/M/L) and 2 colors ⇒ 6 item lines in the feed.

1.2 item_group_id

The item_group_id groups together the items belonging to the same product.

Example:

id: A
item_group_id : 123
color : black
size : S

id: B
item_group_id : 123
color : black
size : L

id: C
item_group_id : 123
color : red
size : M

etc.

Here, 3 items belong to the same product.

Specificities:

• In Sensefuel, the presence of an item_group_id does not require any specific attribute (unlike Google Shopping, which also uses item_group_id but requires at least one of the following attributes: color, material, size, pattern, age_group, gender).
• Your feed may therefore contain an item_group_id grouping items without specifying what varies (size, color, etc.), but this will impact the ability to display variants within the product tile.

Additional consideration if your catalog uses variants grouping (item_group_id)

The "title" attribute must contains a value that is representing a "product title", not a "variant title".
e.g : 
✅ "V neck tee-shirt"

❌ "V neck black tee-shirt S"

2. Variant Levels

Sensefuel manages two levels of variants:

Attribute types are flexible:

→ Any attribute can be used instead of “color” or “size,” allowing the variant model to adapt to your industry/sector/business model/data model.

The variants generations configuration is critical to guarantee the data quality provided by our solution whether you have implemented Sensefuel in Plug & Play (Javascript) or with our APIs.

All the settings must be defined with your CSM.

3. Level 1 Variant – Color & equivalents

3.1 General functioning

Level 1 is used to generate a primary variation such as:

• Color
• Material
• Finish
• Any custom attribute (such as a color code)

3.2 Rendering modes available for Plug & Play integration via the JavaScript tag (Search Layer and Recommend)

🟢 Option 1 – Color swatch

Default configuration is based on the color attribute from your feed.

🔍 Key consideration:

• If the “color” attribute contains a main color (e.g., “blue,” “red”), then this attribute may not be appropriate for generating level 1 variants.
  For example, if a T‑shirt comes in several shades of blue, but the “color” attribute always contains “blue,” Sensefuel will not be able to generate two different color swatches. 
• The color attribute may still contain a main color to ensure good filter behavior and avoid inaccurate color mapping via our algorithm.
  However, in this case you must provide another attribute containing a “precise” color value or at least a color code or equivalent, which will be used in the configuration of the variants generation.

🟦 Option 2 – Hexadecimal color code

Example: #FF5733

Ensures full control over the displayed color swatch.

Based on an attribute containing a hexadecimal value.

🔍 Key consideration:

• You should continue providing the “color” attribute (containing a main color) for color filtering purposes (see previous point).

🖼️ Option 3 – Thumbnail

If you prefer using an image instead of a color swatch.

Possible attributes:

• image_link (default)
• custom attribute containing a dedicated thumbnail image URL (recommended)

4. Level 2 Variant – Size & equivalents

4.1 General functioning

Level 2 is used to generate a secondary variation such as:

• Size
• Pattern
• Format
• Custom attribute

4.2 Rendering modes available for Plug & Play integration via the JavaScript tag (Search Layer and Recommend)

Level 2 never affects:

❌ the product image in the product tile
❌ color swatches or thumbnails

It is simply used to display (or not) additional information representing the second level of variation (S, M, L / 30ml, 50ml / etc.).

The default configuration uses the “size” attribute.

4.2 Specificity: “extrapolation”

Example: if a product exists in:

• blue: S, M
• red: only M

The engine will display S and M for both colors.

Then:

• S will appear greyed out on red (because it does not exist)
• M will appear available

This rule is structural and cannot be disabled.

4.3 Behavior linked to the “availability” attribute

When an item is “out of stock,” the displayed variant appears greyed out.

6. Additional display options for Plug & Play integration via the JavaScript tag (Search Layer and Recommend)

6.1 Variant placement in the product tile

Variants can be positioned:

• inside the image at the bottom
  
• below the image, above the label
  
• below the label and price, or between label and price
  

6.2 Display, forcing, and hiding

The layer also allows you to define when/how the second variant level is displayed:

• on click
  
• on hover (desktop only)
  
• always displayed
  

You can also:

• hide or show a variant level
• force the display even when the product exists in only one level 1 or level 2 variation
  

With layer customization, you can also adjust some behaviors within the technical limits of the Search Layer and the data in your catalog.

7. “Product Split”

The product split is a Sensefuel configuration (can be enabled/disabled).

It allows Sensefuel to duplicate a product tile for each level 1 variant, often the color.
Thus, instead of displaying a single product tile with color swatches/thumbnails, Sensefuel can display one tile per color in the search results list.

Without split:
1 product tile → shows all 3 colors via swatches/thumbnails

With split:
3 product tiles → one per color, with the possibility of also displaying swatches/thumbnails of the other colors

We have observed conversion differences of up to +20% between a non-split and a split version.
Displaying all level 1 variations + their swatches/thumbnails increases catalog exposure and helps customers better understand your offer.

7.1 Split criterion

Defined via an attribute (often the same as the one used for swatches/thumbnails).

⚠️ A built‑in safeguard prevents the generation of identical tiles:
It relies on the image_link attribute — the value must be different for the split to occur.

Limitation:

• If URLs differ but point to identical images → split will still occur.

7.3 Technical impact of split

• When activating the "product split", Sensefuel then generates a new attribute "product_id" that contains the item_group_id value followed by an underscore and the value of the attribute configured as a level 1 variant. 
• The item_group_id remains the same.

8. Impact on price display (price, sale_price, discount %) when items are grouped (Plug & Play integration via the JavaScript tag: Search Layer and Recommend)

When multiple variants attached to the same item_group_id have different prices, a “from” price is automatically generated.

If the items within a grouping have different different discount rates — the Search Layer will generate a label “up to -xx%” for the discount with the maximum discount rate calculated from the difference between your price and sale_price.
The strikethrough price is only displayed when all the variants have the same strikethrough price to avoid inconsistency.

8.1 Possible display modes for the lowest price when product split is enabled

Two modes exist: