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:
| Level | Default configuration | Visual impact | Mandatory? |
|---|---|---|---|
| Level 1 | Color | ✅ Impacts the product image, color swatches or thumbnails | No |
| Level 2 | Size | ⚠️ No impact on the product image; optional informational display | No |
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:
| Mode | Description |
|---|---|
| “Presented” (default and recommended) | Lowest price among the level 2 variants displayed on the tile |
| “Global” | Lowest price based on all variants attached to the same product |