Skip to main content

​
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 reflect unique tile counts, not total variant counts. When a product is broken out by an option (e.g., Color), the facet count increases by the number of unique option values, not the total number of variants. Example: A product with 4 variants (Red/S, Red/M, Blue/S, Blue/M) broken out by Color produces 2 tiles (Red, Blue) and contributes 2 to facet counts, not 4. This deduplication also applies to the tiles themselves. When a product has multiple variants that share the same breakout option value (e.g., Color = “Red” with Size = “S” and Size = “M”), they are collapsed into a single tile. The tile count and facet counts reflect the number of unique option values, not the total number of variants.

​
Default selected options

When you use defaultSelectedOptions alongside variant breakouts, both tile types respect your preferences:
  • Product tiles respect your default selected options. The first_or_matched_variant field will reflect the variant matching your specified option preferences (using OR logic), with a fallback to the first variant by position if no match is found.
  • Variant tiles respect default selected options for non-breakout options. When a product has multiple variants within the same breakout group (e.g., Size = “Small” with Metal = “Gold” and Metal = “Silver”), the tile prefers the variant matching your non-breakout default selected option. The breakout option itself is excluded from matching since the breakout already iterates over those values. If no match is found, the tile falls back to the first variant by position.
For example, a jewelry store could break out products by “Size” while setting a default selected option of Metal = “Silver”. Each size tile (Small, Medium, Large) would then display the Silver variant’s data. If a size only has Gold variants, the tile falls back to the first variant by position.
During text search, keyword-matched variant selection takes priority over default selected options. If keyword features are configured on variant-scoped attributes and the search query matches variant data, the best-matching variant is used instead. See Keyword-matched variant selection for the full priority chain.
See the Browse API defaultSelectedOptions parameter and Search API defaultSelectedOptions parameter for configuration details.

​
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: All
  • Include option value in title: Enabled
Result: Each ring appears as multiple tiles (one per gemstone), allowing customers to browse and compare specific stones directly in search results and collection pages.

​
Fashion brand with color variants

A clothing brand wants to show each color variant as a separate tile in their “New Arrivals” collection. Configuration:
  • Option attribute: Color
  • Applies to: Collections Only
  • Target collections: new-arrivals
  • Include option value in title: Enabled
Result: In the New Arrivals collection, each garment appears once per available color. In search results, products display as standard tiles.

​
Electronics with storage options

A tech retailer sells laptops with different storage configurations (256GB, 512GB, 1TB) at different price points. Configuration:
  • Option attribute: Storage
  • Applies to: Both
  • Target collections: All
  • Include option value in title: Enabled
Result: Each laptop appears as separate tiles per storage option, showing the exact price for each configuration. Customers can filter and sort by the specific storage tier they’re interested in.

​
See also