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.Where capped products go
In a sort order, products that go over the cap move to just below the window. If your window is 24, capped products start right after position 24, ahead of the rest of the collection, instead of dropping to the end of it. Products further down that would also go over the cap can’t move up to fill the window, so the cap holds for every slot inside it. Diversity in a ranking rule’s Spread Results action and a block’s diversity cap works differently: capped products move to the end of the results.When an axis groups by product family, at least one product family must be configured. Without families, that axis has nothing to group by and will have no effect. Attribute axes work as soon as the attribute is populated on your products.
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:- 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.
- Priority rules (promote/demote) apply first, producing a preliminary ordering.
- Diversity reshuffles within the top window to enforce the per-group cap and the coverage floor.
- 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.
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, such as product type, vendor, or color.
- 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.
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.
This scaling applies only when the request supplies a positive page size smaller than the configured window. Requests without page-size input keep the configured window, coverage target, and promotion depth. A larger page size doesn’t expand the configured window.
Minimum unique families
Minimum unique families (the Pull in missing groups 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. In sort orders, Layers reserves room inside the window for these promoted products so they land on the first page rather than just after it.- Range: 0 to 200
- Default: 8 for new diversity expressions. Set it to 0 to turn coverage off. The slider shows Off at 0.
- 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.”
See what diversity changed
When you preview a sort order, the diversity settings show a short summary of what the cap and coverage did to the top window for that preview:- Moves N products out of the top K tells you how many products the cap moved below the window, and how many groups were over the cap.
- Adds N groups that weren’t in the top K tells you how many missing groups coverage pulled into the window.
- No group has more than N products in the top K, so the cap changes nothing here means the preview already met the cap without any changes. Try a lower Max per group if you expected the cap to have an effect.
- Coverage: off appears when Pull in missing groups is set to Off, and Coverage: no missing groups to add appears when the window already had enough groups.
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
These examples assume the request’s page size is at least the configured window, or that the request doesn’t supply page-size input. Smaller page sizes reduce the effective window as described above.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
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
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
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
Top seller exception
Turn on Let top sellers past the cap when you want to keep a family’s strongest sellers visible without letting that family take over the top window. You can use it in sort orders, block diversity safeguards, and ranking-rule diversity actions. First, add a diversity cap. For a family cap, make sure you have assigned related products to product families. The exception is off by default: until you enable it, your existing cap stays unchanged.Choose which sellers qualify
Under Let top sellers past the cap, choose:
These choices identify the sellers eligible for the exception; they don’t change your underlying sort metric or sales window.
Keep the exception bounded
If you cap a family at two products and allow one extra slot, up to three products from that family can stay in the top window—but the extra product must qualify as a top seller. A fourth product still moves down, even if it also qualifies. Other products keep the normal cap. The exception prevents a cap demotion; it doesn’t guarantee a top position or override pins. If you use multiple diversity axes, the extra-slot limit applies separately to each group on each axis. An extra seller from a family also doesn’t count as a new group toward Pull in missing groups.Troubleshooting
- A seller still moves down. Check that it ranks within Top N sellers for your chosen Metric and Sales window, has sales in that window, and hasn’t used up its group’s extra slots. With multiple axes, it must fit within every axis’s normal or extra-slot allowance.
- The first page still feels repetitive. Reduce Extra slots per family or turn off Let top sellers past the cap to return to the normal cap.
Next steps
Preview your changes before publishing. You can configure the exception in a sort order, a block safeguard, or a ranking-rule action. If a cap is hiding a proven seller, review your collection grid insights.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.