Variant breakouts

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:

Select an option attribute (e.g., “Stone”, “Color”, “Size”) that should trigger the breakout
Select where it applies (search results, collection pages, or both)
Target specific collections or apply to all collections
Target specific products (optional) or apply to all products
Choose whether to also target blocks so recommendations expand into variant tiles
Save as draft or publish — new breakouts default to draft status

Once published, 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.

Draft and published status

Variant breakouts have two statuses that control whether they are active:

Published — the breakout is live and actively transforms product tiles into variant tiles in API responses.
Draft — the breakout is saved but not applied. Use drafts to prepare and review configurations before activating them.

When creating a new breakout, you can click Publish to save and activate it immediately, or click Save Draft to save it without activating. When editing an existing breakout, use the Publish or Unpublish buttons to toggle its status. On the variant breakouts list page, you can filter by Status (Published or Draft), Option Attribute, and Collection to quickly find specific configurations.

Block targeting

By default, variant breakouts apply to Browse and Search results but not to block recommendations. Enable Target blocks on a breakout to also expand its products into variant tiles inside block responses.

Off (default) — Blocks continue to return standard product tiles, even when the breakout is active on Browse and Search.
On — Blocks that surface products in scope of the breakout (respecting the breakout’s product and collection targeting) return variant tiles the same way Browse and Search do.

Individual blocks can opt out of variant breakouts entirely using the Disable variant breakouts safeguard. See Rules & safeguards for details.

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 are not applied to the collection while that rule is active. This applies 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.

Exclusion conditions

You can optionally attach a set of conditions to a breakout to exclude variants that match them. The breakout still applies to the same products and collections; matched variants just do not get their own tile. Common uses:

Break out Color, except variants on sale. The sale variant drops out of the tile grid while its siblings keep breaking out normally.
Break out Size, except variants that are out of stock. Sold-out sizes never surface as their own tile even when out-of-stock display is enabled elsewhere.
Break out Metal, except variants below a threshold compare_at_price. Clearance metals stay hidden from the breakout while the full-price metals continue to tile out.

How it applies:

Conditions operate at the variant grain. A variant that matches the condition group produces no tile; its sibling variants keep their tiles, and the product still breaks out for the remaining option values.
If every variant of a product matches the exclusion, the product falls through as one standard product tile. This is the same behavior as a product that doesn’t match the breakout at all.
Conditions run in Browse, Search, blocks (when block targeting is on), and facet counts. Every surface that consumes the breakout inherits the exclusion.
Conditions accept variant-grain fields. That includes variant columns prefixed with variants. (such as variants.on_sale, variants.inventory_quantity, or variants.compare_at_price), variant metafields prefixed with variant_metafields. (such as variant_metafields.custom.material, including nested JSON paths like variant_metafields.custom.specs.weight), and variant options prefixed with options. (such as options.Size or options.Color, matched to the option’s canonical code). Product-level fields are rejected at save time. Variant metafield conditions use the metafield’s declared value type to constrain the available operators. Variant option conditions treat values as strings and support the text operators (equals, does not equal, is in, is not in, contains, begins with, ends with, is empty, is not empty). Codes flagged as restricted or unknown for the store are rejected.
Conditions combine with the same AND/OR combinator used by sort-order when gates and hidden-product rules. Nested groups are not supported. The group is a single flat list of rules.

Exclusions are compiled into the persisted breakout targets. Freshness follows the same reindex cycle as price and inventory changes, so a variant that goes on sale becomes excluded on the next breakout recompute rather than in real time.

The dashboard’s live preview greys out any variant that a condition removes, so you can see the effect before publishing. When a targeted product resolves zero variants only because of conditions, it appears in unresolved targets with the excluded by conditions cause.

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 on the same products

You can configure multiple variant breakouts to work simultaneously across your catalog, including targeting “all collections” with multiple breakouts. When more than one enabled breakout could apply to the same product, Layers picks the winner by scope specificity. The most narrowly scoped breakout owns the product, and broader breakouts remain the fallback for anything the narrower breakout does not cover. Exactly one breakout ever applies to a given product on a given surface. Scope tiers are derived from a breakout’s targeting. Lower-numbered tiers win over higher-numbered tiers:

Targeting	Specific collections	All collections
Specific products	Tier 1	Tier 3
All products	Tier 2	Tier 4

Example. You have a store-wide Color breakout (all collections, all products — tier 4). You want the Sale collection to break out Color for the same products but hide colors that are on sale. Create a second Color breakout scoped to the Sale collection with a variants.on_sale = true exclusion condition (collection-scoped, all products — tier 2). The tier 2 breakout owns the products inside Sale and hides on-sale colors there; the tier 4 breakout keeps expanding every color everywhere else. Validation rules:

Breakouts on different tiers can freely overlap. The lower-tier breakout wins for the products in its scope; the higher-tier breakout keeps running everywhere else.
Breakouts on the same tier cannot overlap. Two same-tier breakouts on the same runtime surface (Search or Collections) and the same collection scope conflict if their product targeting also overlaps (tiers 1 and 3), or unconditionally if they cover all products in that scope (tiers 2 and 4). This applies even when the two breakouts use different option codes. At runtime only one option code ever wins for a product, so the second would silently do nothing.
A search-only breakout and a collections-only breakout never conflict, even at the same tier, because they run on different surfaces. A breakout set to both participates in both surfaces.
Saving a conflicting breakout is rejected with an error naming the tier, the shared collection scope, and any overlapping product IDs. Existing configurations keep working; the rule only fires on the next save.

When a product has multiple options that match different active breakouts (for example, both “Color” and “Stone”), the winning tier’s breakout decides which option splits the product into tiles.

Search uses store-wide breakouts only. Only breakouts that apply to Search and target all collections (tiers 3 and 4) run in Search results. A collection-scoped breakout carries collection-specific rules (targeting, exclusions) that have no meaning outside a collection page, so it is excluded from Search even when its Applies to is Search or Both. If you need collection-specific breakout behavior in Search, use a store-wide breakout instead.

Superseded targets

When you scope a broader breakout (higher tier) alongside a narrower one (lower tier) that owns some of the same products, the narrower breakout supersedes the broader one for its products. The broader breakout still runs everywhere else. Supersession is informational, not blocking. The per-breakout count of superseded products is available programmatically as superseded_product_count on the variant-breakouts MCP tool’s list and get payloads. Breakouts that target all products report no count because they have no enumerable target set.

Search indexing

An enabled variant breakout also tells Layers how to index the affected products for semantic search. When a breakout’s option matches a product’s options, Layers switches that product to per-variant indexing and groups its index entries by the breakout option. The content-selection model no longer makes that call for the matched product.

A ring product with 3 metals × 5 sizes and a breakout on Metal produces 3 text index entries and 3 image index entries — one per metal — instead of 15 of each. Each identity uses the representative variant’s featured image, falling back to the product’s featured image.
Products without the breakout’s option, or with only one value for that option, continue to be indexed at the product level (or by whatever the content-selection model chooses for them).
The breakout drives indexing regardless of its Applies to setting — a breakout scoped to collections still declares an identity-defining option and shapes indexing for that product.
Removing or disabling the breakout returns those products to the model’s per-variant decision on the next reindex.

You can confirm how a product was indexed with the product-search-diagnostics MCP tool. See Diagnosing search coverage.

Unresolved targets

When a breakout targets specific products, Layers verifies that each targeted product actually carries the breakout’s option and records any that do not. These are surfaced in the dashboard so you can catch mistakes and drift — for example, a product whose “Color” option was renamed to “Colour” upstream will stop breaking out silently and instead show up as unresolved. Each unresolved target is tagged with a cause:

no "<option>" option — The product is indexed, but its options do not include the breakout’s option code (typically due to an option rename or a target chosen from the wrong option).
product not yet indexed — The product has not finished indexing. Layers still saves the target and re-checks it once indexing catches up.
only one value for this option — The product has the option but only one value, so there is nothing to break out into multiple tiles.
product not found — The product id no longer exists in the store.
excluded by conditions — The product would break out, but every candidate variant matches the breakout’s exclusion conditions, so nothing is left to tile. Loosen the conditions or drop the product from targeting.

Unresolved targets are recomputed automatically when a product’s options change during sync, and validated whenever you save a breakout. You cannot save a breakout that targets an indexed product missing the option — Layers rejects the save with a validation error. Not-yet-indexed products are allowed through so indexing lag does not block your work.

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:

string

Always "Variant" for variant tiles

number

The variant ID (not the product ID). This is the unique identifier for this specific variant tile.

number

The parent product ID. Use this to link back to the full product or to group variants from the same product.

number

The variant ID (same as id). Included for clarity and consistency.

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.

string

The product handle (inherited from the parent product).

boolean

The availability status of this specific variant.

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.

object

The full variant data for this specific variant, including price, compare_at_price, SKU, and other variant-level attributes.

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Variant breakouts

Overview

How variant breakouts work

Draft and published status

Block targeting

Merchandising rule override

Exclusion conditions

Product targeting

Multiple breakouts on the same products

Superseded targets

Search indexing

Unresolved targets

Tile types

Variant Tiles

Product Tiles

The `__typename` field

Variant tile structure

See also

​Overview

​How variant breakouts work

​Draft and published status

​Block targeting

​Merchandising rule override

​Exclusion conditions

​Product targeting

​Multiple breakouts on the same products

​Superseded targets

​Search indexing

​Unresolved targets

​Tile types

Variant Tiles

Product Tiles

​The __typename field

​Variant tile structure

​See also

Overview

How variant breakouts work

Draft and published status

Block targeting

Merchandising rule override

Exclusion conditions

Product targeting

Multiple breakouts on the same products

Superseded targets

Search indexing

Unresolved targets

Tile types

The `__typename` field

Variant tile structure

See also