Skip to main content

​
Overview

You can edit existing variant breakouts to change their configuration, enable/disable them, or delete them entirely. This guide covers all management operations for variant breakouts.

​
Edit a variant breakout

  1. Go to Merchandising → Variant Breakouts in the dashboard
  2. Find the breakout you want to edit in the list
  3. Click on 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
  • Applies To - Modify where the breakout is active (search, collections, or both)
  • Target Collections - Add or remove collection targets
  • Target Products - Add or remove product targets
  • Include Option Value in Title - Control whether the option value is appended to the product title in variant tiles
Changing the option attribute will immediately affect which products are broken out into variant tiles. Ensure the new option exists on the products you want to target.
  1. Click Save Changes to apply your modifications

​
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.
Draft breakouts are saved but not applied to results. This is useful for testing or temporarily reverting to standard product tiles without losing your configuration.

​
Delete a variant breakout

Deleting a variant breakout is permanent and cannot be undone. Products will immediately revert to displaying as standard product tiles.
  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

​
Validation rules

When editing a breakout, Layers enforces these rules:

​
Overlap prevention

You cannot publish a breakout if it overlaps with another published breakout that has the same option code. The overlap logic depends on product targeting: Without product targeting:
  • Breakouts with the same option code cannot target overlapping collections
  • Multiple breakouts with different option codes can target the same collections without conflict
With product targeting:
  • Breakouts with the same option code and both having product targeting cannot have overlapping products AND collections
  • A breakout with product targeting can coexist with a breakout without product targeting on the same collections (they target different scopes)
  • Breakouts with product targeting that target different products can coexist on the same collections
If you encounter an overlap error:
  1. Change the option code to a different value, or
  2. Add or modify product targeting to create a distinct scope, or
  3. Unpublish the conflicting breakout with the same option code, or
  4. Modify the target collections or products to remove the overlap, or
  5. Delete the conflicting breakout with the same option code

​
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

When editing a breakout, consider unpublishing it first, making your changes, testing in a staging environment, then publishing it again.
Name your breakouts clearly so team members understand their purpose (e.g., “Gemstone Breakout for Jewelry” instead of “Breakout 1”).
Keep notes on why you configured breakouts for specific collections. This helps when reviewing or optimizing your merchandising strategy.
After enabling or modifying a breakout, check your facet counts to ensure they align with expectations.

​
Troubleshooting

Check for validation errors:
  • Ensure no other published breakout with the same option code targets overlapping collections and products
  • Consider adding product targeting to create a distinct scope that won’t conflict
  • Verify the option attribute exists and is spelled correctly
  • Confirm you have products with this option in the target collections
Note: Multiple breakouts with different option codes can target the same collections without conflict. Breakouts with product targeting can coexist with breakouts without product targeting on the same collections.
  • Verify the breakout is published after saving
  • Clear any caching in your frontend application
  • Check that you’re viewing a collection or search result where the breakout applies
Unfortunately, deletions are permanent. You’ll need to recreate the breakout with the same configuration. Consider unpublishing instead of deleting if you might need the configuration again.

​
See also