Configuration & behavior

​

Configuration options

​

Applies to

Control where your variant breakout is active. In the breakout editor, this is the Surface field in the Where it applies card:

• Search & Collections (default) — 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)

Use Applies to to set different display strategies for search and browse.

​

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

When more than one enabled breakout can apply to a 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. A collection-scoped breakout can layer on top of a store-wide breakout on the same products without a conflict. The collection-scoped one owns its collection, and the store-wide one keeps working everywhere else. Only same-tier scopes on the same surface conflict at save time. See Multiple breakouts on the same products for the tier table and the full validation rules.

​

Excluded collections

You can optionally list collections the breakout must never run on. Exclusions are subtracted from the breakout’s targeting:

• A store-wide breakout with exclusions applies to every collection except the excluded ones.
• A collection-scoped breakout with exclusions applies to its targeted collections minus the excluded ones.

On an excluded collection page, products stay as single standard product tiles instead of expanding into variant tiles. Exclusions do not change the breakout’s scope tier, and a store-wide breakout with exclusions still runs in Search. You cannot list the same collection as both a target and an exclusion; Layers rejects the save with a validation error. See Excluded collections for the full behavior.

​

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 on the same collections: Product targeting lets multiple breakouts, with the same or different option codes, coexist on the same collections. A breakout with product targeting sits on a more specific scope tier than a breakout without product targeting, so the two don’t conflict, and the product-targeted one wins for its products. Two product-targeted breakouts on the same tier and surface also coexist as long as they target different products. Overlap checks ignore the option code, so two same-tier breakouts that cover the same products conflict even when they break out different options.

​

Exclusion conditions

Attach conditions to a breakout to exclude variants that match them. Conditions accept three kinds of variant-grain fields. Use variant fields (variants.*) such as variants.on_sale, variants.inventory_quantity, or variants.compare_at_price. Use variant metafields (variant_metafields.*) such as variant_metafields.custom.material, including nested JSON paths like variant_metafields.custom.specs.weight. Use variant options (options.*) such as options.Size or options.Color to match on the option value a variant is assigned. Rules combine with an AND/OR combinator across a single flat list. Nested groups aren’t supported. Matched variants don’t produce a tile:

• Sibling variants still break out for their option values.
• If every candidate variant matches the exclusion, the product falls through as a single standard product tile.
• Exclusions run in Browse, Search, blocks (when block targeting is on), and facet counts.

Common examples:

• Break out Color, except variants.on_sale = true.
• Break out Size, except variants.inventory_quantity <= 0.
• Break out Metal, except variants.compare_at_price below a floor.
• Break out Style, except variant_metafields.custom.discontinued = true.
• Break out Color, except options.Size = 'Small' to hide the small size while every other size still tiles out.

Variant metafield conditions use the metafield’s declared value type (string, number, boolean, or datetime) to determine which operators are available. Metafield codes that are restricted from filtering are rejected at save time. Unknown metafield codes that haven’t been indexed for the store are also rejected. Variant option conditions (options.*) treat values as strings and support equals, does not equal, is in, is not in, contains, begins with, ends with, is empty, and is not empty. Layers matches the option name against the option’s canonical code, so options.Size and options.size refer to the same option. Options that don’t exist on the store’s catalog are rejected at save time.

​

Target blocks

Control whether the breakout also applies to block recommendations:

• Off (default) — The breakout only affects Browse and Search results. Blocks continue to return standard product tiles.
• On — Blocks return variant tiles for products in scope of the breakout, matching the behavior on Browse and Search.

Block targeting respects the breakout’s product and collection targeting. A block only receives variant tiles when its anchor context (product or collection) falls within the breakout’s scope. Individual blocks can override this with the Disable variant breakouts safeguard. See Rules & safeguards.

​

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

Include option value in title is set per breakout. Enable it 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.

​

Out-of-stock behavior

Variant breakouts respect your store’s out-of-stock settings at the individual tile level:

​

Hiding out-of-stock variants

When you disable Show out-of-stock products, Layers hides out-of-stock variant tiles from results, even if the parent product has other in-stock variants. Only variant tiles with available inventory appear.

​

Demoting out-of-stock variants

When you enable Demote out-of-stock products (and showing out-of-stock is also enabled), Layers pushes out-of-stock variant tiles to the end of results. In-stock variant tiles maintain their normal sort order among themselves.

​

Sell-out pin behavior

When Delete Pins on Sell Out is enabled on a merchandising rule, a pinned product is only unpinned when all of its variants are out of stock. If at least one variant still has inventory, the pin remains active.

​

Pinning variant tiles

Merchandising rules support pinning individual variant tiles to specific positions. When creating a pin in a merchandising rule, you can select one of two pin types:

• Product pin — Pins the entire product (or the product tile for non-breakout products)
• Variant pin — Pins a specific variant tile to a position

Variant pins control which variant appears in a specific position on the collection page. For example, you can pin the “Rose Quartz” variant of a ring to position 1 and the “Amethyst” variant of the same ring to position 3.

​

Unserved variant pins

A variant pin can point at a tile that no breakout covering the rule’s collection actually emits. This happens when a breakout is narrowed, disabled, or deleted after the pin was created, or when the rule’s Disable Variant Breakouts toggle is on. The storefront skips the pin, and every pin below it shifts up one position. Layers surfaces these pins instead of hiding them:

• In the editor — Pinned variant tiles that the storefront skips show a Not served here badge. When another enabled breakout already emits the variant but doesn’t cover this collection, the badge tooltip names that breakout so you know which one to widen. The rule sidebar shows a count of unserved variant pins. Badges refresh as you change the collection or the Disable Variant Breakouts toggle, before you save.
• On save — Saving a merchandising rule that holds unserved variant pins reports how many pinned variant tiles are not served by any breakout covering the collection. The save still succeeds.
• On breakout changes — Editing a variant breakout in a way that narrows its coverage, or disabling, deleting, or unpublishing it, reports which rules lose pinned variant tiles and how many. See Edit or delete a variant breakout.

To fix an unserved variant pin, either widen the breakout named in the tooltip to cover the collection, create a breakout that covers it, or replace the variant pin with a product pin.

​

Duplicate tiles

When a rule pins the same product both as a product pin and as a variant pin, the storefront can show the same item twice. The editor flags this with a Duplicate tile badge on the affected cards and a count in the rule sidebar. Remove one of the two pins to resolve it.

​

Similar product search

The Similar Products API does not apply your store’s variant breakouts. When you call it directly, results return standard product tiles regardless of your variant breakout configuration. Blocks that use a Similar Products strategy (including the behavior-seeded variants) are different. Like every other block strategy, they return variant tiles when a breakout has Target blocks turned on and covers the products in scope, unless the block uses the Disable variant breakouts safeguard.