Skip to main content

​
Overview

Variant Breakouts allow you to transform how products with multiple variants are displayed in your catalog. Instead of showing a single product tile that represents all variants, you can configure specific product options (like Stone, Color, or Size) to be “broken out” into individual variant tiles. This feature is particularly powerful for products where each variant represents a distinct item that customers want to browse and compare independently, such as jewelry with different gemstones, apparel in different colors, or products with meaningful size variations.

​
How Variant Breakouts Work

When you create a variant breakout configuration:
  1. Select an option attribute (e.g., “Stone”, “Color”, “Size”) that should trigger the breakout
  2. Choose where it applies (search results, collection pages, or both)
  3. Target specific collections or apply to all collections
  4. Enable the breakout to activate the behavior
Once enabled, products that have the specified option will be expanded into individual variant tiles in the configured locations. Products without that option continue to display as standard product tiles.

​
Multiple Breakouts in the Same Collection

You can configure multiple variant breakouts with different option codes to work simultaneously in the same collection. This allows products with different option structures to be broken out appropriately:
  • Product A with a “Color” option can be broken out by color
  • Product B with a “Stone” option can be broken out by stone
  • Both products can appear in the same collection with their respective breakouts active
When a product has multiple options that match different active breakouts (e.g., both “Color” and “Stone”), the product will be broken out by the first matching option code based on the order the breakouts were created.

​
Tile Types

With variant breakouts enabled, your Browse and Search API responses will contain two types of tiles:

Variant Tiles

Individual variants from products with the breakout option. Each tile represents a specific variant and includes the variant’s unique data (price, availability, images).

Product Tiles

Standard product representations for products without the breakout option. These tiles aggregate data from all variants of the product.

​
The __typename Field

When variant breakouts are enabled, all results include a __typename field that identifies the tile type:
  • "Product" - A standard product tile
  • "Variant" - An individual variant tile from a broken-out product
This field allows your frontend to render different UI components or styling based on the tile type.
Example Response with Mixed Tiles
{
  "results": [
    {
      "__typename": "Variant",
      "id": 43000000001,
      "product_id": 7003338965178,
      "variant_id": 43000000001,
      "title": "Amethyst Ring - Rose Quartz",
      "handle": "amethyst-ring",
      "available": true,
      "first_or_matched_variant": {
        "id": 43000000001,
        "price": "45.00",
        "available": true
      }
    },
    {
      "__typename": "Product",
      "id": 7003338965179,
      "title": "Silver Necklace",
      "handle": "silver-necklace",
      "available": true,
      "first_or_matched_variant": {
        "id": 43000000010,
        "price": "89.00",
        "available": true
      }
    }
  ]
}

​
Variant Tile Structure

Variant tiles have a unique structure compared to product tiles:
​
__typename
string
Always "Variant" for variant tiles
​
id
number
The variant ID (not the product ID). This is the unique identifier for this specific variant tile.
​
product_id
number
The parent product ID. Use this to link back to the full product or to group variants from the same product.
​
variant_id
number
The variant ID (same as id). Included for clarity and consistency.
​
title
string
The variant-specific title in the format "{product title} - {option value}". For example: "Amethyst Ring - Rose Quartz".
​
handle
string
The product handle (inherited from the parent product).
​
available
boolean
The availability status of this specific variant.
​
first_or_matched_variant
object
The full variant data for this specific variant, including price, compare_at_price, SKU, and other variant-level attributes.

​
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 collection, allowing products with different option structures to be broken out appropriately within a single collection.

​
Impact on API Responses

​
Total Results and Pagination

When variant breakouts are enabled, totalResults reflects the count of tiles (not products). A single product with 5 variants will contribute 5 to the total count. Pagination also operates on tiles:
  • page and limit parameters control tile pagination
  • totalPages is calculated based on tile count
Example Pagination
{
  "totalResults": 47,  // 10 products + 1 product with 37 variants
  "page": 1,
  "totalPages": 5,     // With limit: 10
  "results": [/* 10 tiles */]
}

​
Facet Counts

Facet counts also reflect tile counts rather than product counts. If you have a facet for “vendor” and a product from “VendorA” has 3 variants broken out, the facet count for “VendorA” will increase by 3 (not 1). This ensures that facet counts accurately represent what customers see in the results.

​
Filtering and Sorting

Filters and sort orders operate on tiles:
  • Price filters apply to the variant’s price (for variant tiles) or the first variant’s price (for product tiles)
  • Availability filters apply to the variant’s availability status
  • Sorting by price uses the tile’s price, ensuring variant tiles sort by their specific variant price

​
Variant-Level Metrics in Sort Orders

When using LayersQL metrics that include variant_id in their GROUP BY clause, the sorting behavior adapts based on tile type:
  • Variant tiles are sorted using their individual variant-level metric values
  • Product tiles are sorted using product-level metric values (aggregated across all variants)
This conditional sorting ensures accurate ranking for both tile types. For example, a metric defined as: 
FROM products
SHOW SUM(total_sales)
GROUP BY product_id, variant_id
SINCE -7d
When used in a sort order with variant breakouts enabled, each variant tile will be ranked by its specific sales performance, while product tiles (for products without the breakout option) will be ranked by their total product sales. See Variant-Level Metrics for more details on creating and using these metrics.

​
When to Use Variant Breakouts

Variant breakouts are ideal when:

Distinct Variants

Each variant represents a meaningfully different product that customers want to browse independently (e.g., different gemstones, distinct colorways).

Visual Comparison

Customers benefit from seeing multiple variants side-by-side with their individual images and prices.

Variant-Level Merchandising

You want to pin or promote specific variants rather than entire products.

Improved Discovery

Breaking out variants helps customers discover options they might miss in a standard product tile.

​
When Not to Use Variant Breakouts

Avoid variant breakouts when:
  • Variants are simple size or quantity variations (e.g., Small/Medium/Large t-shirts)
  • You have products with many variants (20+) that would clutter the results
  • Variants don’t have distinct images or meaningful differences
  • Your customers prefer to select variants on the product detail page

​
Best Practices

Select option attributes where each value represents a distinct item customers want to compare. “Stone” or “Color” often work well, while “Size” may not.
Variant breakouts work best when each variant has its own image. If all variants share the same image, the breakout may not provide value.
Start by applying breakouts to specific collections to test the experience before rolling out to all collections.
Remember that facet counts will reflect tile counts. Communicate this to your team to avoid confusion when analyzing metrics.
Use the __typename field to render variant tiles differently from product tiles. Consider showing the variant-specific title and a “View Product” link.

​
Example Use Cases

​
Jewelry Store with Gemstone Options

A jewelry store sells rings with different gemstone options (Amethyst, Rose Quartz, Tiger Eye). Each gemstone has a different price and image. Configuration:
  • Option attribute: Stone
  • Applies to: Both
  • Target collections: rings, gemstone-jewelry
Result: Customers browsing the “Rings” collection see individual tiles for each gemstone variant, making it easy to compare prices and styles across different stones.

​
Apparel Store with Colorways

A streetwear store sells limited-edition hoodies where each colorway is a distinct release with its own branding and pricing. Configuration:
  • Option attribute: Color
  • Applies to: Collections Only
  • Target collections: hoodies, limited-edition
Result: Collection pages show each colorway as a separate tile, while search results still show products (allowing customers to find the product first, then explore colorways).

​
Art Prints with Size Variations

An art store sells prints in multiple sizes, but each size has significantly different pricing and framing options. Configuration:
  • Option attribute: Size
  • Applies to: Both
  • Target collections: All collections
Result: Customers can browse and filter by specific print sizes, seeing the exact price for each size option directly in the results.

​
Mixed Catalog with Multiple Breakout Options

A lifestyle store sells both jewelry (with “Stone” options) and apparel (with “Color” options) in the same “New Arrivals” collection. Configuration:
  • Breakout 1: Option attribute Stone, applies to Both, target collections: All collections
  • Breakout 2: Option attribute Color, applies to Both, target collections: All collections
Result: In the “New Arrivals” collection, jewelry products are broken out by stone (showing individual gemstone variants), while apparel products are broken out by color (showing individual colorway variants). Products without either option display as standard product tiles. The _meta.variantBreakouts array in the API response includes both breakout configurations.

​
See Also