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 works well for products where each variant represents a distinct item that customers want to browse and compare independently. Examples include 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. Select 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.
​
featured_media
object
The media for this variant tile. Uses the variant’s own featured media when available; falls back to the parent product’s featured media when the variant does not have one assigned.
​
first_or_matched_variant
object
The full variant data for this specific variant, including price, compare_at_price, SKU, and other variant-level attributes.

​
See also