> For the complete documentation index, see [llms.txt](https://docs.abtasty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abtasty.com/recommendations-and-merchandising/concepts/strategies/rules/custom-rules/diversification-rules.md).
# Diversification rules
The **Diversification rule** enables automatic reordering of products to ensure a balanced and varied product display, while preserving the overall ranking logic.
### **Overview**
Diversification helps avoid repetitive product sequences (e.g. same brand or similar items) and improves product discovery without sacrificing performance.
Key benefits include:
* Improved **product discovery**
* Reduced **visual repetition**
* Increased **engagement and CTR**
* Maintained **business control and performance**
### **How it works**
When applied, Diversification does the following:
* **Runs on the final returned set**: It executes after all other custom rules, filters, and maximum display limits (e.g., a cap of 8 items) have already been applied.
* **Reorders existing results only**: The algorithm does not fetch replacement items from your catalog. It only shuffles the existing list of products that successfully passed your prior rules to maximize variation across the selected attributes.
* **Functions on a best-effort basis**: If the final list of products contains a high concentration of identical values (for example, if 6 out of 8 products share the same brand or fiche\_id), the algorithm will spread them out as much as possible (e.g., A, B, A, B, A, A, A, A). However, visual repetitions will inevitably remain because there are not enough distinct values in the final subset to completely avoid consecutive duplication.
* **Modifies display order only**: Product scores and underlying strategy logic remain unchanged.
### **Where it applies**
The **Diversification rule** is applied on the overall strategy, after all ranking and rules have been executed. This ensures global diversity across all combined rules.
**Example:** avoiding multiple products from the same brand across a full recommendation list.
### **Attribute support**
Diversification can be configured on any product attribute available in the catalog, regardless of type:
| Type | Examples |
| ------- | ------------------------------ |
| String | `brand` , `category` , `color` |
| Numeric | `price` , `rating` , `margin` |
| Boolean | `on_sale` , `new_arrival` |
Up to **3 attributes** can be combined simultaneously.
{% hint style="warning" %}
**The order of attributes matters**
When you select multiple diversification fields, they are not treated as an unordered set. Instead, they follow a strict hierarchy based on the order in which you list them (e.g., \[ "category", "brand" ] behaves differently than \[ "brand", "category" ]):
1. Primary Field: Diversification is executed first on your first attribute.
2. Secondary Tie-Breakers: If the algorithm evaluates multiple candidate positions that are equally valid under the first attribute (i.e. "ties remain"), it will use the second attribute to break the tie and further reorder those items.
**Example:** Consider three items already sorted by recommendation score:
* Product 1 (Category: Shoes / Brand: Nike)
* Product 2 (Category: Shoes / Brand: Nike)
* Product 3 (Category: Shoes / Brand: Adidas)
* If you diversify only on \["category"], there is no secondary rule to resolve the category tie, and the display order remains unchanged: \[P1, P2, P3].
* If you diversify on \["category", "brand"], the category tie remains, but the system uses brand as a tie-breaker, shifting the Adidas shoe to break up the consecutive Nike products: \[P1, P3, P2].
{% endhint %}
### **Typical use cases**
Common scenarios where diversification is useful include:
* Avoiding showing multiple products from the same brand consecutively
* Mixing different product types within a category (e.g. a skincare routine)
* Balancing price ranges within a recommendation list
* Alternating between promotional and full-price products
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.abtasty.com/recommendations-and-merchandising/concepts/strategies/rules/custom-rules/diversification-rules.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
