Skip to main content

​
Overview

Variant Breakouts allow you to transform how products with multiple variants are displayed in your catalog. Instead of showing a single product tile that represents all variants, you can configure specific product options (like Stone, Color, or Size) to be “broken out” into individual variant tiles. This feature is particularly powerful for products where each variant represents a distinct item that customers want to browse and compare independently, such as jewelry with different gemstones, apparel in different colors, or products with meaningful size variations.

​
How Variant Breakouts Work

When you create a variant breakout configuration:
  1. Select an option attribute (e.g., “Stone”, “Color”, “Size”) that should trigger the breakout
  2. Choose where it applies (search results, collection pages, or both)
  3. Target specific collections or apply to all collections
  4. Target specific products (optional) or apply to all products
  5. Enable the breakout to activate the behavior
Once enabled, products that have the specified option will be expanded into individual variant tiles in the configured locations. Products without that option continue to display as standard product tiles.

​
Merchandising Rule Override

Merchandising rules can override variant breakout behavior for a collection. When a merchandising rule has the Disable Variant Breakouts option enabled, variant breakouts will not be applied to the collection while that rule is active, regardless of your variant breakout configuration. This allows you to temporarily disable variant breakouts for specific merchandising campaigns, contextual conditions, or scheduled events without modifying your global variant breakout settings. See Merchandising Rules for more information.

​
Product Targeting

You can optionally target specific products for a variant breakout. When product targeting is configured:
  • Without product targeting - The breakout applies to all products (within the target collections) that have the specified option
  • With product targeting - The breakout only applies to the selected products (within the target collections)
AND logic: When you combine product targeting with collection targeting, both conditions must be met. The breakout only applies to the selected products AND within the selected collections. This allows you to create highly specific breakout configurations for particular product lines or featured items.

​
Multiple Breakouts in the Same Collection

You can configure multiple variant breakouts with different option codes to work simultaneously in the same collection, including targeting “all collections” with multiple breakouts. This allows products with different option structures to be broken out appropriately:
  • Product A with a “Color” option can be broken out by color
  • Product B with a “Stone” option can be broken out by stone
  • Both products can appear in the same collection with their respective breakouts active
  • Both breakouts can target “all collections” without conflict
Validation rules:
  • Multiple breakouts with different option codes can target the same collections (including “all collections”)
  • Breakouts with the same option code cannot target overlapping collections AND products
  • Breakouts with product targeting can coexist with breakouts without product targeting (they target different scopes)
Overlap logic:
  • If both breakouts have no product targeting, they cannot overlap on collections (for the same option code)
  • If both breakouts have product targeting, they cannot overlap on both collections AND products (for the same option code)
  • If one has product targeting and one doesn’t, they can overlap on collections because the one with product targeting only applies to specific products
When a product has multiple options that match different active breakouts (e.g., both “Color” and “Stone”), the product will be broken out by the first matching option code based on the order the breakouts were created.

​
Tile Types

With variant breakouts enabled, your Browse and Search API responses will contain two types of tiles:

Variant Tiles

Individual variants from products with the breakout option. Each tile represents a specific variant and includes the variant’s unique data (price, availability, images).

Product Tiles

Standard product representations for products without the breakout option. These tiles aggregate data from all variants of the product.

​
The __typename Field

When variant breakouts are enabled, all results include a __typename field that identifies the tile type:
  • "Product" - A standard product tile
  • "Variant" - An individual variant tile from a broken-out product
This field allows your frontend to render different UI components or styling based on the tile type.
Example Response with Mixed Tiles
{
  "results": [
    {
      "__typename": "Variant",
      "id": 43000000001,
      "product_id": 7003338965178,
      "variant_id": 43000000001,
      "title": "Amethyst Ring - Rose Quartz",
      "handle": "amethyst-ring",
      "available": true,
      "first_or_matched_variant": {
        "id": 43000000001,
        "price": "45.00",
        "available": true
      }
    },
    {
      "__typename": "Product",
      "id": 7003338965179,
      "title": "Silver Necklace",
      "handle": "silver-necklace",
      "available": true,
      "first_or_matched_variant": {
        "id": 43000000010,
        "price": "89.00",
        "available": true
      }
    }
  ]
}

​
Variant Tile Structure

Variant tiles have a unique structure compared to product tiles:
​
__typename
string
Always "Variant" for variant tiles
​
id
number
The variant ID (not the product ID). This is the unique identifier for this specific variant tile.
​
product_id
number
The parent product ID. Use this to link back to the full product or to group variants from the same product.
​
variant_id
number
The variant ID (same as id). Included for clarity and consistency.
​
title
string
The variant tile title. By default, this is formatted as "{product title} - {option value}" (e.g., "Amethyst Ring - Rose Quartz"). If the breakout’s “Include Option Value in Title” setting is disabled, this will be the original product title without modification.
​
handle
string
The product handle (inherited from the parent product).
​
available
boolean
The availability status of this specific variant.
​
first_or_matched_variant
object
The full variant data for this specific variant, including price, compare_at_price, SKU, and other variant-level attributes.

​
Configuration Options

​
Applies To

Control where your variant breakout is active:
  • Both - 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)
This allows you to have different display strategies for search versus browse experiences.

​
Target Collections

You can configure variant breakouts to apply:
  • To all collections - Leave the target collections field empty
  • To specific collections - Select one or more collection handles
Multiple variant breakouts with different option codes can target the same collections (including “all collections”), allowing products with different option structures to be broken out appropriately. However, breakouts with the same option code cannot target overlapping collections (unless they have distinct product targeting).

​
Target Products

You can optionally configure variant breakouts to apply only to specific products:
  • To all products - Leave the target products field empty (default)
  • To specific products - Select one or more products
AND logic with collections: When you combine product targeting with collection targeting, the breakout only applies to the selected products within the selected collections. For example, if you target products A and B in collection “clothing”, the breakout only affects those two products when browsing the “clothing” collection. Coexistence with same option code: Product targeting allows multiple breakouts with the same option code to coexist on the same collections. A breakout with product targeting only applies to those specific products, so it won’t conflict with a breakout without product targeting (which applies to all other products) or with another breakout targeting different products.

​
Include Option Value in Title

Control whether variant tile titles include the option value:
  • Enabled (default) - Variant tiles display titles in the format "{product title} - {option value}" (e.g., “Amethyst Ring - Rose Quartz”)
  • Disabled - Variant tiles use the original product title without modification
This setting is configurable per breakout, allowing you to customize title formatting based on your catalog structure and customer preferences. Enable this when the option value provides meaningful context; disable it when the product title already includes sufficient variant information or when you prefer a cleaner display.

​
Impact on API Responses

​
Total Results and Pagination

When variant breakouts are enabled, totalResults reflects the count of tiles (not products). A single product with 5 variants will contribute 5 to the total count. Pagination also operates on tiles:
  • page and limit parameters control tile pagination
  • totalPages is calculated based on tile count
Example Pagination
{
  "totalResults": 47,  // 10 products + 1 product with 37 variants
  "page": 1,
  "totalPages": 5,     // With limit: 10
  "results": [/* 10 tiles */]
}

​
Facet Counts

Facet counts also reflect tile counts rather than product counts. If you have a facet for “vendor” and a product from “VendorA” has 3 variants broken out, the facet count for “VendorA” will increase by 3 (not 1). This ensures that facet counts accurately represent what customers see in the results.

​
Filtering and Sorting

Filters and sort orders operate on tiles:
  • Price filters apply to the variant’s price (for variant tiles) or the first variant’s price (for product tiles)
  • Availability filters apply to the variant’s availability status
  • Sorting by price uses the tile’s price, ensuring variant tiles sort by their specific variant price

​
Variant-Level Metrics in Sort Orders

When using LayersQL metrics that include variant_id in their GROUP BY clause, the sorting behavior adapts based on tile type:
  • Variant tiles are sorted using their individual variant-level metric values
  • Product tiles are sorted using product-level metric values (aggregated across all variants)
This conditional sorting ensures accurate ranking for both tile types. For example, a metric defined as: 
FROM products
SHOW SUM(total_sales)
GROUP BY product_id, variant_id
SINCE -7d
When used in a sort order with variant breakouts enabled, each variant tile will be ranked by its specific sales performance, while product tiles (for products without the breakout option) will be ranked by their total product sales. See Variant-Level Metrics for more details on creating and using these metrics.

​
When to Use Variant Breakouts

Variant breakouts are ideal when:

Distinct Variants

Each variant represents a meaningfully different product that customers want to browse independently (e.g., different gemstones, distinct colorways).

Visual Comparison

Customers benefit from seeing multiple variants side-by-side with their individual images and prices.

Variant-Level Merchandising

You want to pin or promote specific variants rather than entire products.

Improved Discovery

Breaking out variants helps customers discover options they might miss in a standard product tile.

​
When Not to Use Variant Breakouts

Avoid variant breakouts when:
  • Variants are simple size or quantity variations (e.g., Small/Medium/Large t-shirts)
  • You have products with many variants (20+) that would clutter the results
  • Variants don’t have distinct images or meaningful differences
  • Your customers prefer to select variants on the product detail page

​
Best Practices

Select option attributes where each value represents a distinct item customers want to compare. “Stone” or “Color” often work well, while “Size” may not.
Variant breakouts work best when each variant has its own image. If all variants share the same image, the breakout may not provide value.
Start by applying breakouts to specific collections to test the experience before rolling out to all collections.
Remember that facet counts will reflect tile counts. Communicate this to your team to avoid confusion when analyzing metrics.
Use the __typename field to render variant tiles differently from product tiles. Consider showing the variant-specific title and a “View Product” link.

​
Example Use Cases

​
Jewelry Store with Gemstone Options

A jewelry store sells rings with different gemstone options (Amethyst, Rose Quartz, Tiger Eye). Each gemstone has a different price and image. Configuration:
  • Option attribute: Stone
  • Applies to: Both
  • Target collections: rings, gemstone-jewelry
Result: Customers browsing the “Rings” collection see individual tiles for each gemstone variant, making it easy to compare prices and styles across different stones.

​
Apparel Store with Colorways

A streetwear store sells limited-edition hoodies where each colorway is a distinct release with its own branding and pricing. Configuration:
  • Option attribute: Color
  • Applies to: Collections Only
  • Target collections: hoodies, limited-edition
Result: Collection pages show each colorway as a separate tile, while search results still show products (allowing customers to find the product first, then explore colorways).

​
Art Prints with Size Variations

An art store sells prints in multiple sizes, but each size has significantly different pricing and framing options. Configuration:
  • Option attribute: Size
  • Applies to: Both
  • Target collections: All collections
Result: Customers can browse and filter by specific print sizes, seeing the exact price for each size option directly in the results.

​
Mixed Catalog with Multiple Breakout Options

A lifestyle store sells both jewelry (with “Stone” options) and apparel (with “Color” options) in the same “New Arrivals” collection. Configuration:
  • Breakout 1: Option attribute Stone, applies to Both, target collections: All collections, target products: All products
  • Breakout 2: Option attribute Color, applies to Both, target collections: All collections, target products: All products
Result: In the “New Arrivals” collection, jewelry products are broken out by stone (showing individual gemstone variants), while apparel products are broken out by color (showing individual colorway variants). Products without either option display as standard product tiles. The _meta.variantBreakouts array in the API response includes both breakout configurations. Why this works: The two breakouts use different option codes (Stone and Color), so they can both target “all collections” without conflict. If you tried to create a second breakout with the Stone option code targeting all collections, it would be blocked by validation. A jewelry store wants to break out gemstone variants for premium rings only, while keeping standard rings as product tiles. Configuration:
  • Option attribute: Stone
  • Applies to: Both
  • Target collections: rings
  • Target products: Premium Amethyst Ring, Premium Rose Quartz Ring, Premium Tiger Eye Ring
Result: Only the three selected premium ring products are broken out into individual gemstone variant tiles in the “rings” collection. All other rings display as standard product tiles. This allows the store to highlight specific products while maintaining a cleaner display for the rest of the catalog.

​
Coexisting Breakouts with Product Targeting

A clothing store wants different color breakout strategies for premium and basic product lines in the same collection. Configuration:
  • Breakout 1: Option attribute Color, applies to Both, target collections: clothing, target products: Premium Hoodie, Premium T-Shirt
  • Breakout 2: Option attribute Color, applies to Both, target collections: clothing, target products: Basic Hoodie, Basic T-Shirt
Result: Both breakouts use the same option code (Color) and target the same collection (clothing), but they don’t conflict because they target different products. The premium products are broken out by the first breakout, and the basic products are broken out by the second breakout. This demonstrates how product targeting creates distinct scopes that allow breakouts with the same option code to coexist.

​
See Also