Skip to main content

​
Overview

Variant breakouts allow you to configure specific product options (like Stone, Color, or Size) to be displayed as individual variant tiles instead of a single product tile. This is useful when each variant represents a distinct item that customers want to browse and compare independently.

​
Before You Begin

  • Ensure you have products with the option attribute you want to break out (e.g., products with a “Stone” option)
  • Verify that variants have unique images and meaningful differences
  • Consider which collections would benefit from variant breakouts

​
Create a Variant Breakout

  1. Navigate to Merchandising → Variant Breakouts in the dashboard
  2. Click Create Breakout
  3. Configure the breakout settings:

​
Name

Enter a descriptive name for your breakout configuration (e.g., “Stone Breakout” or “Color Breakout for Apparel”).

​
Option Attribute

Select the product option attribute that should trigger the breakout. This dropdown shows all option attributes in your catalog (attributes that start with options.). Examples:
  • Stone - For jewelry with different gemstones
  • Color - For apparel with distinct colorways
  • Size - For products where size represents meaningfully different items
Choose an option where each value represents a distinct item customers want to compare. Avoid options like “Size” for standard clothing where customers typically select size on the product page.

​
Applies To

Choose where the variant breakout should be active:
  • Search & Collections - Applies to both search results and collection browse pages
  • Collections Only - Only applies to collection browse pages (Browse API)
  • Search Only - Only applies to search results (Search API)
You can use different strategies for search versus browse. For example, show variants in collections but keep products grouped in search results.

​
Target Collections

Specify which collections should use this breakout:
  • All Collections - Leave this field empty to apply the breakout to all collections
  • Specific Collections - Select one or more collection handles to target specific collections
You cannot have overlapping collection targets. Each collection can only have one active variant breakout at a time. If you try to create a breakout that targets a collection already covered by another breakout, you’ll receive a validation error.

​
Enable/Disable

Toggle the breakout on or off. Disabled breakouts are saved but not applied to results.

​
Save the Breakout

Click Create Breakout to save your configuration. The breakout will be immediately active if enabled.

​
What Happens Next

Once your variant breakout is active:
  1. Products with the option will be expanded into individual variant tiles
  2. Products without the option will continue to display as standard product tiles
  3. API responses will include a __typename field identifying each tile as "Product" or "Variant"
  4. Total results and facet counts will reflect tile counts (not product counts)
  5. Pagination will operate on tiles

​
Example Scenario

Goal: Display rings with different gemstones as individual tiles in the “Rings” collection. Configuration:
  • Name: Gemstone Breakout
  • Option Attribute: Stone
  • Applies To: Both
  • Target Collections: rings, gemstone-jewelry
  • Enabled: Yes
Result: When customers browse the “Rings” collection, they see individual tiles for each gemstone variant (Amethyst Ring, Rose Quartz Ring, Tiger Eye Ring) instead of a single “Ring” product tile.

​
Troubleshooting

  • Verify the breakout is enabled
  • Check that you’re viewing a collection or search result where the breakout applies
  • Ensure products in the collection have the specified option attribute
  • Confirm the option attribute name matches exactly (case-sensitive)
Another active breakout already targets one or more of the collections you selected. You must either:
  • Disable the existing breakout
  • Remove the overlapping collections from one of the breakouts
  • Use different collection targets
This is expected behavior. When variant breakouts are enabled, facet counts reflect tile counts rather than product counts. A product with 5 variants will contribute 5 to the facet count.
Ensure each variant has its own image assigned in Shopify. Variant breakouts work best when variants have distinct visual representations.

​
Next Steps

​
See Also