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. Navigate 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
  • 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
  • Enabled - Toggle the breakout on or off
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

​
Enable or Disable a Breakout

You can temporarily disable a breakout without deleting it:

​
From the Edit Page

  1. Navigate to the breakout’s edit page
  2. Toggle the Enabled switch to off
  3. Click Save Changes

​
From the List Page

  1. Navigate to Merchandising → Variant Breakouts
  2. Find the breakout in the list
  3. Click the enable/disable toggle in the Status column
Disabled 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. Navigate to the breakout’s edit page
  2. Scroll to the bottom of the page
  3. Click Delete
  4. Confirm the deletion in the dialog

​
What Happens When You Delete

  • The breakout configuration is permanently removed
  • 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
  • Any merchandising rules pinning variant tiles will need to be updated

​
Validation Rules

When editing a breakout, the system enforces these rules:

​
Overlap Prevention

You cannot enable a breakout if it overlaps with another active 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. Disable 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 disabling it first, making your changes, testing in a staging environment, then re-enabling it.
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 active 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 enabled 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 disabling instead of deleting if you might need the configuration again.

​
See Also