Edit or delete a variant breakout

​

Overview

You can edit existing variant breakouts to change their configuration, enable/disable them, or delete them entirely.

​

Edit a variant breakout

1. Go to Merchandise → Variant Breakouts in the dashboard
2. Find the breakout you want to edit in the list
3. Click the breakout name to open the edit page
4. Modify any of the following settings:

​

Editable fields

• Name — Update the descriptive name (editable inline in the page header)
• Option Attribute — Change which product option triggers the breakout
• Surface — Modify where the breakout is active (Search & Collections, Collections Only, or Search Only)
• Target Collections — Add or remove collection targets
• Target Products — Add or remove product targets
• Conditions — Add, edit, or remove variant-level exclusion conditions that keep matching variants from breaking out
• Include Option Value in Title — Control whether the option value is appended to the product title in variant tiles

5. Click Save Changes to apply your modifications

​

Warnings about pinned variant tiles

Merchandising rules can pin variant tiles that depend on a breakout serving them. When a change to a breakout stops serving pinned variant tiles, the confirmation reports which rules are affected and how many pins each rule loses. For example: “This change stopped serving 4 pinned variant tiles: Statement Rings (3), New Arrivals (1).” The warning appears when you:

• Save an edit that narrows the breakout’s coverage, such as adding target collections to a store-wide breakout, removing a target collection or product, adding an exclusion, or moving Applies To off collections
• Disable, unpublish, or delete the breakout

The change still saves. The affected pins stay on their rules and show a Not served here badge in the merchandising editor until you widen a breakout to cover them or replace them with product pins. See unserved variant pins.

​

Publish or unpublish a breakout

You can control whether a breakout is live using the Publish and Unpublish buttons in the page header:

1. Go to the breakout’s edit page
2. Click Publish to make a draft breakout live, or Unpublish to revert a published breakout to draft status

You can also filter the breakout list by status using the Status column filter. Select Published or Draft to narrow the list. The Status column also tracks the rebuild that follows publishing. A published breakout shows a Publishing badge with a spinner while Layers rebuilds its collection scope, Failed if the rebuild fails, and Published once the change is live.

​

Review unresolved targets

When a breakout targets specific products, the breakout list and edit page flag any targets that Layers cannot break out. Use these flags to catch stale product ids and options that have drifted (for example, a product whose option was renamed upstream).

​

On the breakouts list

A small warning icon appears next to a breakout’s name when it has one or more unresolved targets. Hover the icon to see how many targets could not be resolved and the reason: the products are missing, still indexing, or excluded by the breakout’s own exclusion conditions. Open the breakout to see the per-product cause and fix it.

​

On the edit page

Each selected product row shows an inline status when the target cannot be broken out:

• no "<option>" option — The product is indexed but does not have the breakout’s option. Remove it, select a product that has the option, or change the breakout’s option attribute.
• product not yet indexed — The product is still indexing. The target is kept and re-checked automatically once indexing completes.
• only one value for this option — The product only has one value for the option, so there is nothing to break out. Consider removing it.
• product not found — The product id no longer exists in the store. Remove it.
• excluded by conditions — Every candidate variant matches the breakout’s exclusion conditions, so nothing is left to tile. Loosen the conditions or drop the product from targeting.

The preview panel also seeds from the first unresolved target when one exists, so mismatches surface immediately instead of hiding behind a healthy sample product. When the breakout targets more than one product, use the Preview product select on the Preview card to check how each of the other targets splits into tiles.

​

Delete a variant breakout

1. Go to the breakout’s edit page
2. Open the overflow menu (the three-dot icon in the page header)
3. Click Delete Breakout
4. Confirm the deletion in the dialog

​

What happens when you delete

• Layers permanently removes the breakout configuration
• Products immediately revert to standard product tiles
• API responses no longer include __typename fields (unless other breakouts are active)
• Facet counts return to product-based counting
• You need to update any merchandising rules that pin variant tiles. The deletion confirmation lists the rules that lose pinned variant tiles, and the affected pins show a Not served here badge in the merchandising editor

​

Validation rules

When editing a breakout, Layers enforces these rules:

​

Overlap prevention

You cannot publish a breakout if it collides with another published breakout at the same scope tier. The option code doesn’t matter: two breakouts can conflict even when they break out different options (for example, Color and Stone), because only one breakout ever applies to a given product on a given surface. A breakout’s scope tier comes from its targeting:

• Tier 1 — Specific collections and specific products
• Tier 2 — Specific collections, all products
• Tier 3 — All collections, specific products
• Tier 4 — All collections, all products

Two published breakouts conflict only when all of the following are true:

• They are on the same tier. Breakouts on different tiers can cover the same products; the more specific (lower-numbered) tier wins for its products, and the broader one keeps running everywhere else.
• They run on the same surface. A Search Only breakout and a Collections Only breakout never conflict. A Search & Collections breakout shares a surface with both.
• Their collection scopes overlap, after subtracting each breakout’s excluded collections.
• For tiers 1 and 3, they also target at least one of the same products. Tier 2 and tier 4 breakouts cover every product in their scope, so a shared collection scope is enough to conflict.

If you encounter an overlap error:

1. Add or remove product targeting or collection targeting so the two breakouts sit on different tiers, or
2. Remove the overlapping products or collections from one of the breakouts, or
3. Set one breakout to Search Only and the other to Collections Only, or
4. Unpublish or delete the conflicting breakout

The error names the tier, the conflicting breakout, the shared collections, and any overlapping product IDs. See Multiple breakouts on the same products for more on how tiers resolve at runtime.

​

Option attribute validation

The option attribute must:

• Exist in your catalog
• Be a valid option attribute (starts with options.)
• Have products that use this option

​

Best practices

​

Troubleshooting

​

See also

• Create a variant breakout
• Variant Breakouts Overview
• Merchandising Rules