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.

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”) as long as they target different products.
Breakouts with the same option code cannot target overlapping collections when neither uses product targeting.
A breakout that targets all products (no product targeting) still coexists with product-targeted breakouts — the product-targeted one wins for its specific products, and the catch-all covers the rest.
Any product can only be targeted by one enabled breakout per applies-to domain, regardless of option code. Two product-targeted breakouts that both apply to the same surface (search results or collection pages) cannot list the same product, even if they use different option codes. Breakouts on separate surfaces — for example, a search-only breakout and a collections-only breakout — can safely target the same product because they never run in the same query. A breakout that applies to both surfaces participates in both, so it still conflicts with any same-product breakout on either side.

At runtime a product is broken out by a single option code within each surface. Because of that, saving two product-targeted breakouts that share a product on the same surface is rejected — one of them would silently do nothing for the overlapping product. Existing configurations keep working; the rule only fires on the next save. Option codes are compared case-insensitively, so Color and color are treated as the same code. When a product has multiple options that match different active breakouts (e.g., both “Color” and “Stone”), the product is broken out by the highest-priority option code that actually targets it. Priority is set by the order breakouts appear in the applicable list.

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.

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

Product targeting

Multiple breakouts in the same collection

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

​Product targeting

​Multiple breakouts in the same collection

​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

Product targeting

Multiple breakouts in the same collection

Unresolved targets

Tile types

The `__typename` field

Variant tile structure

See also