Diversity expressions in sort orders

​

What diversity does

A diversity expression limits how many products from the same group are allowed in the top K positions of a sort order or merchandising rule. Without it, the first page can show six near-duplicates of the same style in a row. With it, more distinct products surface before a customer has to scroll. Groups are defined by one or more diversity axes. An axis can group by product family or by any categorical attribute, such as product type, vendor, or color. When you configure multiple axes on the same expression, each axis enforces its own cap independently. A product only enters the top window if it fits under every axis at once. Diversity acts on the top window only. Beyond the window, products fall back to their natural sort order and repeats are allowed again.

​

When to use diversity

Use diversity when your catalog contains many variations of the same underlying style and the first page of a collection feels repetitive. Common scenarios:

• A best-selling t-shirt is available in eight colors and all eight dominate the top of the collection.
• A top-ranked furniture piece ships in five fabrics and pushes every other product off page one.
• A vendor has multiple near-identical SKUs that all score similarly on your sort order.
• One product type (say, dresses) crowds out other types on a broad “New arrivals” collection. Use a second axis on product_type to keep categories mixed alongside a family cap.

​

How diversity fits with other sort features

Diversity layers on top of your base sort order and respects higher-priority controls:

1. Pins (merchandised, ranking rule, or dynamic) stay in their pinned position and are exempt from the cap. A pinned product never consumes a slot under the per-group limit, so its organic siblings still get the full Max per group allowance. A pinned member does count its group as represented for the coverage floor.
2. Priority rules (promote/demote) apply first, producing a preliminary ordering.
3. Diversity reshuffles within the top window to enforce the per-group cap and the coverage floor.
4. Soft boost, metrics, and attributes continue to determine ordering within the window.

​

Configuration parameters

Diversity works the same way in sort orders and merchandising rules. You add it in two places:

• In a sort order, click Add Expression and choose Product Diversity.
• In a merchandising rule, add an expression and choose Product Diversity. In the rule’s expression list, it’s shown as Family Diversity.

A sort order or merchandising rule can hold one diversity expression. The UI exposes the same core fields in both locations.

​

Diversity axes

Each axis defines one dimension the expression will spread across. Add up to five axes to the same diversity expression. For example, use one axis on product family and a second on product type. Every axis has two settings:

• Group by — Either Product Family or Product Attribute. You choose the axis type from the Add axis menu when you create the axis, and it is fixed after that. To switch an existing axis between family and attribute, remove it and add a new one. Attribute axes require you to pick an attribute (typically a categorical one like product_type, vendor, or a color feature).
• Max per group — The maximum number of products that can share the same value on this axis inside the window.
  • Range: 1 to 10 in the editor (1 to 100 accepted in payloads).
  • Default: 1 for new diversity expressions.

When multiple axes are configured, a product only enters the top window if it stays under every axis cap simultaneously. That means adding a second axis makes the mix stricter, not looser. Start with one axis and add more only when a single group dimension isn’t enough.

​

Window size

Window size is the number of top positions where the cap and coverage rules apply. Beyond this window, natural sort order resumes and repeats are allowed.

• Range: 1 to 200
• Default: 20
• Guidance: Match the window to the first page of your collection grid. If your storefront shows 24 products per page, a window of 24 is a reasonable starting point.

​

Minimum unique families

Minimum unique families (the Group coverage slider in the editor) is a coverage floor. If fewer than this many distinct families appear in the window after the cap is applied, the top-scoring first-occurrence of each missing family is promoted up to fill the gap.

• Range: 0 to 200
• Default: 8 for new diversity expressions. Set it to 0 to turn coverage off.
• Guidance: Use when you want to guarantee a minimum breadth on the first page. For example, “I want at least 10 different styles in the top 20.”

​

Products without a group

Products that have no value on an axis (for example, no family assignment or a missing attribute) are left out of diversity. They keep their natural sort position, never count against the per-group cap, and don’t count toward the coverage floor. The sort order and merchandising rule editors always save diversity this way and don’t show a setting for it. The alternative, where each ungrouped product counts as its own group toward the coverage floor, is available only when you configure a sort order or merchandising rule through the Layers API or MCP server. You can’t select it in the dashboard.

​

Examples

​

Cap color variants on a best-seller collection

A “Best Sellers” collection keeps surfacing the same hoodie in every color. You want at most two variants of any one style in the top 20. Settings

• Window size: 20
• Axis 1: Group by Product Family, Max per group 2
• Minimum unique families: 0

Result: At most two products from any single family (for example, the hoodie) appear in the first 20 positions. The third-best-selling color drops out of the top window and re-enters below it. Products without a family are unaffected.

​

Guarantee at least 10 distinct styles in the top 20

You want the first page of a seasonal collection to always feel broad, even if a handful of styles outperform everyone else. Settings

• Window size: 20
• Axis 1: Group by Product Family, Max per group 2
• Minimum unique families: 10

Result: After the per-family cap is applied, if the top 20 contains fewer than 10 distinct families, Layers promotes the highest-scoring first-occurrence of each missing family up into the window until the floor is met.

​

Brand-level diversity

You use a manual family to group everything from a single private-label brand so it cannot dominate the top window. Settings

• Window size: 24
• Axis 1: Group by Product Family, Max per group 3
• Minimum unique families: 0

Result: No more than three products from the grouped brand appear in the first 24 positions.

​

Mix families and product types on a broad landing collection

Your “New arrivals” collection surfaces the newest products across the whole catalog, but the first page keeps filling up with dresses from one or two families. You want variety on both dimensions. Settings

• Window size: 20
• Axis 1: Group by Product Family, Max per group 2
• Axis 2: Group by Product Attribute → product_type, Max per group 4
• Minimum unique families: 0

Result: Products only enter the top 20 if they fit under both caps: no more than two products from the same family and no more than four products of the same product type. A third dress from any family, or a fifth dress overall, drops out of the window and re-enters below it.

​

Best practices

• Start with defaults. New diversity expressions start with a window of 20, a cap of 1 per family, and a coverage floor of 8 on a single family axis. Raise the cap to 2 if the first page feels too sparse for collections with few families.
• Add axes one at a time. Extra axes only make the mix stricter. Ship a single-axis rule first, preview it, and only add a second axis if one dimension isn’t enough to break up the top window.
• Preview every change. Diversity noticeably reshuffles the first page. Always use the sort order preview or merchandising rule preview before saving.
• Check family coverage first. A family axis has no effect on products that aren’t assigned to a family. Before tuning, confirm that your families cover the products you care about.
• Use coverage sparingly. A high coverage floor can push weak matches into the top window. Raise it gradually and verify the preview still looks right.
• Combine with priority rules, not against them. A priority rule and a diversity expression in the same sort order can compose well. Promote a brand with a priority rule, then cap variants with diversity.

​

See also

• Product families
• Create a product family
• Sort orders
• Merchandising rules
• Priority rules