Skip to main content

​
Configuration options

​
Applies to

Control where your variant breakout is active:
  • Both - 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)
This allows you to have different display strategies for search versus browse experiences.

​
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
Multiple variant breakouts with different option codes can target the same collections (including “all collections”), allowing products with different option structures to be broken out appropriately. However, breakouts with the same option code cannot target overlapping collections (unless they have distinct product targeting).

​
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 with same option code: Product targeting allows multiple breakouts with the same option code to coexist on the same collections. A breakout with product targeting only applies to those specific products, so it won’t conflict with a breakout without product targeting (which applies to all other products) or with another breakout targeting different products.

​
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
This setting is configurable per breakout, allowing you to customize title formatting based on your catalog structure and customer preferences. Enable this 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 Show out-of-stock products is disabled, out-of-stock variant tiles are completely hidden from results, even if the parent product has other in-stock variants. Only variant tiles with available inventory are displayed.

​
Demoting out-of-stock variants

When Demote out-of-stock products is enabled (and showing out-of-stock is also enabled), out-of-stock variant tiles are pushed to the end of results. In-stock variant tiles maintain their normal sort order among themselves.
These settings apply per tile. A product with 5 color variants where 2 are out of stock will show 3 tiles when hiding is enabled, or show all 5 tiles with the 2 out-of-stock variants demoted to the end when demotion is enabled.

​
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 choose between:
  • 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 allow you to control exactly 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.
Variant pins only take effect when variant breakouts are active for the collection. If variant breakouts are disabled (either globally or via a merchandising rule override), variant pins are ignored.
Variant breakouts are not applied to similar product searches. When using the Similar Products API, results always return standard product tiles regardless of your variant breakout configuration. This ensures that similar product recommendations remain product-level comparisons.