> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/how-recommendations-work.md).

# How recommendations work

How InsightSearch selects the products for a recommendation block: filters, candidates, weighting, diversity and AI signals explained step by step.

This page explains what happens between a page view in your shop and the products shown in a recommendation block. Once you know in which order filters, weighting and boosters apply, you can set up templates with intent and understand why a block sometimes shows more products and sometimes fewer.

You do not need this page to get started. It helps as soon as you adjust templates or want to understand a result.

## The short version

For every recommendation block on a page, your visitor's browser sends one request to InsightSearch. The request carries the settings of your template: recommendation type, filters, weighting, boosters and number of products. InsightSearch calculates the list and sends it back. The plugin then checks in your shop whether the visitor may see the products and adds fixed products or fallback products.

There are two kinds of recommendations, and they are calculated differently:

| Kind                | Recommendation types                                                                                                                             | How it is calculated                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| For a product       | "Similar products (alternatives)", also in the cart and the off-canvas cart                                                                      | Full calculation with filters, weighting, boosters and diversity                                 |
| From behaviour data | Bestsellers, Trending now, Recently viewed, You may also like, Goes well with, Continue where you left off, Buy again, Inspired by your wishlist | A ranking from orders or visitor behaviour, followed only by exclusions, rules and a stock check |

What each type needs is described in [Recommendation types](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/recommendation-types.md).

## Recommendations for a product, step by step

### 1. Collect the settings

InsightSearch takes over the values of your template. Fields you leave empty are replaced by InsightSearch defaults. In the template form you can recognise these defaults by the "Default" badge on the sliders. After that, the AI settings from **Products & data → AI** apply (see below).

### 2. Load the source product

The product the recommendations refer to is the source product (also called "reference product" in the Administration). On the product page it is the product shown. In the cart, the field "Cart: reference product" decides which line item counts: highest line value, highest unit price, last added, or "Mix of several lines". With the mix, InsightSearch calculates separately for up to five line items and merges the lists in turn.

If InsightSearch cannot find the source product in your product data (for example a brand new product before the next synchronisation), no list comes back. In that case the fallback you set in the template applies.

### 3. Hard filters

Filters decide which products qualify at all. Weighting cannot bring back a product that a filter has excluded. InsightSearch applies them in this order:

1. The source product itself is always excluded.
2. Variants of the source product are excluded.
3. "Only in stock", if you added this block in the rule builder. Shopware's availability is what counts.
4. The "Mode": "Only same brand" or "Only same category". For the category, the product's main category counts. If the source product has no brand or category, the mode is dropped.
5. Your rules from the rule builder, also with reference to the source product, for example the same colour or a similar price range (±20 %).
6. Products already in the cart, including their variants (always in the cart and off-canvas cart, elsewhere with the cart exclusion switch).

More about rules in [Filters and rule builder](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/filters-and-rule-builder.md).

### 4. Collect candidates

InsightSearch looks for matching products in up to four sources at the same time. The same filters apply to every source.

* **AI similarity:** products that are close to the source product in content, even with different wording or in another category.
* **Product data:** same brand, same or related categories.
* **Shopper behaviour:** products that visitors added to the cart or viewed together with the source product.
* **Neighbours calculated overnight:** similar products that InsightSearch determines in advance every night.

If one source fails, the others keep delivering.

### 5. Final check

Every candidate is checked once more. Duplicates are removed. Of several variants of the same product only one remains. With "Disallow identical title" (on by default) products with the same name appear only once.

### 6. Scoring (weighting)

Now every candidate receives a score for similarity. It is made up of nine shares that you set in the "Weighting" section of the template: category, brand, content similarity (AI), price, shopper behaviour, popularity, context, attributes and tags. Each weight counts as a share of the sum of all weights.

Two things matter:

* **Missing data is not penalised.** If a product has no AI data, no shopper behaviour or no popularity yet, that share is simply left out for this product. The remaining shares count more.
* **Scores are relative.** AI similarity and price proximity are rated relative to the other candidates. The best candidate receives the full value.

Then the **boosters** are added. Boosters are extra points for products that meet a condition, for example "Prefer products in stock" or the brand and category boosts in expert mode. The setting "Minimum similarity score" checks the similarity **without** boosters. A booster therefore never lifts an unsuitable product above this threshold.

Details are in [Weighting, diversity and boosters](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/weighting-and-boosters.md).

### 7. Diversity

In the "Mixed" mode, InsightSearch makes sure that the list does not consist of products from just one brand or one category. Each further slot goes to the product that matches well and differs from those already chosen. The brand of the source product is held back a little more. How strong this is depends on "Diversity" in expert mode. In the modes "Only same brand" and "Only same category" this step is skipped.

### 8. Relax instead of returning nothing

If there are not enough matches for the requested number, InsightSearch relaxes carefully:

* In the mode "Only same category", the search widens to the parent category. The closer matches stay in front.
* Stock, rules and exclusions remain in place at every stage. InsightSearch never fills up without filters.

If there are still not enough products, fewer products come back. Then the template's fallback applies if you set one ("Fallback type" and "Fallback threshold" in the "Display" section).

### 9. Visibility in the shop

If "Only show products the customer may see" is active in the plugin configuration (on by default), the plugin requests a few more products than needed. It then hides everything the customer may not see in your shop, for example because of the customer group or the sales channel. This way enough products remain. Fixed products are placed first by the plugin. They count towards the number of products.

## Recommendations from behaviour data

For Bestsellers, Trending now, Recently viewed, You may also like, Goes well with, Continue where you left off, Buy again and Inspired by your wishlist, a data source provides the order, for example the orders of the last 30 days. After that only the following happens:

1. Exclusions: the source product (if there is one) and products in the cart including their variants.
2. Rules and mode of the template, but only if a source product is sent along.
3. Stock check and only one variant per product.

{% hint style="warning" %}
Weighting, boosters and diversity have no effect on these types. The order comes from the behaviour data alone. Changing the sliders in the form does not change the result.
{% endhint %}

## The AI signals

InsightSearch uses several AI-based signals. You control them in the plugin dashboard under **Products & data → AI**. This section is currently shown in German; the labels are quoted as they appear.

| Setting                                                           | Effect                                                                                                                                                          |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Bedeutungs-Ähnlichkeit (KI)" (semantic similarity)               | Recommends products that are similar in content, even in another category or with different wording. Off: classic recommendations by brand, category and price. |
| "Kaufverhalten einbeziehen" (include shopper behaviour)           | Takes into account which products your visitors buy or view together. Calculated overnight.                                                                     |
| "Gewichtung der KI" (AI weighting)                                | Strengthens or weakens the AI share in all recommendations of this data source. 1.0× matches the settings of the templates.                                     |
| "Beschreibung für KI-Ähnlichkeit" (description for AI similarity) | How much of the product description flows into AI similarity: shortened, full or not used. A change recalculates the AI data in the background.                 |
| "Insight-Analyse" (insight analysis, beta)                        | Evaluates orders, clicks and searches daily and provides bestsellers, trends and popularity for your recommendations.                                           |

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-ebad483066009c255ead9bf10e510c70bd7d15cb%2Fcross-selling-pro-or-ki-%2B-warenkorb-cross-selling-%2B-bundles-and-sets-ki-funktionen.png?alt=media" alt="AI section in the plugin dashboard with the AI features"><figcaption></figcaption></figure>

### How the AI data is created

* **Content similarity:** title, brand, category, attributes and, depending on the setting, the description form a pattern for each product. This data is kept after a reindex. Only changed products are processed again.
* **Similar products and shopper behaviour:** recalculated every night. Shopper behaviour only appears once at least three visits have added the same two products to the cart together or viewed them together. After larger changes to your range you can start the calculation immediately with "Jetzt neu berechnen" (recalculate now), at most once per hour.
* **Popularity:** a value per product from clicks, add-to-cart actions and orders of the last 30 days. It is only created with the insight analysis switched on. Without it, the "Popularity" share in the weighting has no effect.

The AI section shows how far the data has come: AI preparation, products with AI neighbours and products with purchase signals.

{% hint style="info" %}
"Similar products (alternatives)" is essentially a similarity calculation. Real accessories instead of similar products come mainly from shopper behaviour, from rules (for example a category other than the source product's) or from the "Accessories (product page)" preset. As long as your shop has collected little shopper behaviour, this type tends to show similar products.
{% endhint %}

## Fallback route during disruptions

InsightSearch always calculates with the current method. During a disruption an older method takes over automatically so that the block does not stay empty. The preview of a template shows this with a note that the calculation used the older method.

## Read more

{% content-ref url="/pages/g0MBU0n7PXv3za1OYjZh" %}
[Recommendation types](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/recommendation-types.md)
{% endcontent-ref %}

{% content-ref url="/pages/OxFN5VKGROb1uxX81J2Q" %}
[Weighting, diversity and boosters](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/weighting-and-boosters.md)
{% endcontent-ref %}

{% content-ref url="/pages/aG6vtzB13aErytbtzpSe" %}
[Preview and sandbox](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/preview-and-sandbox.md)
{% endcontent-ref %}

{% content-ref url="/pages/e00VEeT8TubzE8TB5J6M" %}
[When do changes take effect?](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/when-changes-take-effect.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/how-recommendations-work.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
