> 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/recommendation-templates.md).

# Creating recommendation templates

Every field of a recommendation template in Cross Selling Pro, from quick start to display, with its effect and default value.

This page is the reference for the recommendation template form. It lists every card and every field with its effect, its default value and the plan from which it is available. For a first overview, read [Templates](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/templates.md) first. How filters, weighting and boosters calculate in detail is covered on separate pages.

## Creating or editing a template

1. In the Shopware Administration open **Content → InsightSearch**.
2. In the sidebar choose **Delivery → Recommendation templates**.
3. Click “Create template” at the top right, or click the name of an existing template.
4. Fill in the cards from top to bottom.
5. Click “Save”.

At the top right you also find “Support”, “Cancel” and the switch “Show expert mode”. Expert mode shows additional fields. It is not saved and is off again the next time you open the template. If a template already contains filter rules, expert mode switches on by itself when you open it, so that you can see the rules.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-22692866fc9f0a6fa351906c73e515c5122e131f%2Fcross-selling-pro-or-ki-%2B-warenkorb-cross-selling-%2B-bundles-and-sets-vorlage-bearbeiten.png?alt=media" alt="Recommendation template form with the Quick start, General, Source and Filter cards"><figcaption></figcaption></figure>

{% hint style="info" %}
The “Preview” card only appears once the template has been saved. Save a new template early so you can check the result straight away. See [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).
{% endhint %}

### What a new template starts with

| Setting               | Starting value                                          |
| --------------------- | ------------------------------------------------------- |
| “Recommendation type” | “Similar products (alternatives)”                       |
| “Source”              | “InsightSearch API”                                     |
| “Product type”        | “Same type” (only takes effect once enabled, see below) |
| Filter rules          | none                                                    |
| “Limit”               | 6                                                       |
| “Button action”       | “Add to cart”                                           |
| “Fallback type”       | “No fallback”                                           |

Empty number fields mean “InsightSearch default”. A new template does not save its own weights, it always uses the current default values.

## Card “Quick start”

A “Preset” sets the recommendation type and configuration to proven starting values for one use case. You can change every value afterwards. Below the field you see what the preset is based on, and “All presets explained” expands a description of all presets.

For a template that has already been saved, the form asks first (“Apply preset?”). The preset replaces type, source, filters, weighting and boosters. Count, button, fallback and existing filter rules are kept.

| Preset                                            | Recommendation type         | What it sets                                                                                                             |
| ------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| “Automatic (recommended)”                         | Similar products            | mode “Mixed”, minimum similarity 0.05, products in stock preferred. A good default for most shops.                       |
| “Same category & price range”                     | Similar products            | mode “Only same category”, price deviation 0.4, minimum similarity 0.05, in stock preferred                              |
| “Same brand”                                      | Similar products            | mode “Only same brand”, in stock preferred                                                                               |
| “Accessories (product page)”                      | Similar products            | shopper behaviour weighted higher, product type “Matching types”, in stock preferred                                     |
| “Cart: matching accessories”                      | Similar products            | shopper behaviour weighted higher, “Matching types”, reference product “Mix”, cart products excluded, in stock preferred |
| “Frequently bought together (purchase data only)” | Goes well with              | order data only, from 2 joint purchases                                                                                  |
| “Bestsellers”                                     | Bestsellers                 | best-selling products, e.g. for the home page                                                                            |
| “Trends”                                          | Trending now                | trending products, e.g. for the home page                                                                                |
| “Personal”                                        | You may also like           | needs tracking data                                                                                                      |
| “Recently viewed”                                 | Recently viewed             | needs tracking data                                                                                                      |
| “Continue where you left off”                     | Continue where you left off | products from carts that were never ordered                                                                              |
| “Buy again”                                       | Buy again                   | products the customer ordered before                                                                                     |
| “Inspired by your wishlist”                       | Inspired by your wishlist   | similar products to items on the wishlist                                                                                |

The behaviour presets (from “Frequently bought together” onwards) switch the product type off. If a preset's type is not included in your plan, a lock with the required plan appears next to its name. Clicking it opens the plan overview instead of applying the preset.

## Card “General”

| Field                 | Effect                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| “Name”                | Required. Internal name for identification in the Administration, not visible to customers.                                     |
| “Recommendation type” | Determines what kind of recommendations the template produces. “What do the recommendation types mean?” expands an explanation. |
| “Description”         | Optional internal note, for example which pages the template is used on. Longer texts are possible.                             |

### The recommendation types

| Type (Administration label)                                              | In short                                                                                                   | Plan         |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------ |
| “Similar products (alternatives)”                                        | products matching the reference product. Uses product content and works from day one, even without orders. | from Basic   |
| “Recently viewed”                                                        | products the visitor viewed most recently                                                                  | from Basic   |
| “Bestsellers”                                                            | best-selling products of the shop                                                                          | from Starter |
| “Buy again (products from your order history)”                           | products the logged-in customer ordered before                                                             | from Starter |
| “Goes well with (frequently bought together)”                            | uses real order data, needs order history                                                                  | from Expert  |
| “Trending now”                                                           | products in demand right now                                                                               | from Expert  |
| “You may also like”                                                      | recommendations based on the visitor's behaviour                                                           | from Expert  |
| “Continue where you left off (products added to cart but never ordered)” | products from earlier carts that were never ordered                                                        | from Expert  |
| “Inspired by your wishlist”                                              | similar products to items on the wishlist                                                                  | from Expert  |

Which data each type needs and what it shows without data is explained in [Recommendation types](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/recommendation-types.md). If the selected type is not included in your plan, the form shows a lock notice with the required plan.

## Card “Expert mode”

This card only appears when expert mode is on. It counts how many expert settings differ from the default, for example “1 expert setting differs from the default.”

* “Reset all expert settings” sets all switches and numbers of the expert mode back to their defaults. Source, mode, product type, weighting, filter rules, boosters and display stay unchanged. The change takes effect once you save.
* Every field that differs has the link “Reset to default”.

## 1. Source

Here you define where the products come from.

| Field                       | Effect                                                                                                                                                                                                                                                                                                                                                             | Default                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| “Source”                    | “InsightSearch API”: InsightSearch calculates recommendations based on type, filters and weighting. “Dynamic product stream”: shows the products of a Shopware product stream. “Bundle/Set template”: shows the products of a bundle/set template. “Cross-selling (from reference product)”: shows the Shopware cross-selling maintained on the reference product. | “InsightSearch API”                     |
| “Fallback product stream”   | Only with the source “Dynamic product stream”: the product stream whose products are shown. The field carries this label here, but it is the actual source.                                                                                                                                                                                                        | empty                                   |
| “Bundle/Set template”       | Only with the source “Bundle/Set template”: the template whose products are shown                                                                                                                                                                                                                                                                                  | empty                                   |
| “Cross-selling name”        | Only with the source “Cross-selling”: optional name of the cross-selling on the product                                                                                                                                                                                                                                                                            | empty                                   |
| “Cross-selling position”    | Only with the source “Cross-selling”: which cross-selling is used when no name is set (1 = the first)                                                                                                                                                                                                                                                              | 1                                       |
| “Product source”            | Only with “InsightSearch API” and type “Similar products”: “Automatic (PDP)” uses the product of the current page as reference.                                                                                                                                                                                                                                    | “Automatic (PDP)”                       |
| “Cart: reference product”   | Only with “InsightSearch API” and type “Similar products”. Applies only to the off-canvas cart and the cart page, see below.                                                                                                                                                                                                                                       | “Highest line value (price × quantity)” |
| “Fixed products”            | These products are shown first and count towards the limit. From plan Starter.                                                                                                                                                                                                                                                                                     | none                                    |
| “Minimum co-purchase count” | Expert mode only. For purchase-based recommendations: product pairs must have been bought together at least this many times (1 to 50).                                                                                                                                                                                                                             | InsightSearch default                   |

{% hint style="warning" %}
If “Dynamic product stream” or “Bundle/Set template” is selected but nothing has been chosen yet, the form does not save. It shows “Not saved: a selection is still missing in section “1. Source”.”
{% endhint %}

### Reference product in the cart

A cart holds several products. The field “Cart: reference product” decides which product the recommendations are based on:

| Option                                  | Meaning                                                                                                                                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| “Highest line value (price × quantity)” | the line with the highest total value                                                                                                                                                      |
| “Highest unit price”                    | the most expensive single product                                                                                                                                                          |
| “Most recently added”                   | the product added to the cart last                                                                                                                                                         |
| “Mix of several lines”                  | looks up to five lines (most expensive first) and interleaves the results. With many lines, InsightSearch stops adding lines after about one second so the cart does not load more slowly. |

### Fixed products

{% hint style="info" %}
Available from plan Starter.
{% endhint %}

Fixed products always come first. They count towards the limit: with “Limit” 6 and two fixed products, four calculated recommendations are added. A fixed product that is currently being viewed or is already in the cart is left out. Fixed products apply wherever the template runs. For a promotion on only a few pages, create a separate template.

### Shop sources: what still applies?

With “Dynamic product stream”, “Bundle/Set template” and “Cross-selling” the shop supplies the products itself. The form then shows the box “What applies with this source?”:

| Applies                                                                         | No effect                                                                                        |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Count, button, fixed products (placed first), fallback, “Exclude cart products” | Recommendation type (plan and placement only), quick start presets, filters, weighting, boosters |

The cards “Quick start”, “2. Filters”, “3. Weighting” and “4. Boosters” stay visible but are greyed out. Your values stay saved and apply again as soon as you switch back to “InsightSearch API”.

{% hint style="warning" %}
The source “Cross-selling” needs a reference product. Product pages and the cart provide one, the customer account and the off-canvas cart do not. The block stays empty there.
{% endhint %}

## 2. Filters

Filters decide strictly which products qualify at all. No weighting brings back what a filter excludes. At the top, the box “In short: what this template filters” sums up all active filters in plain language.

| Field                      | Effect                                                                                                                                                                                              | Default                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| “Mode”                     | “Mixed”: no tie, similarity decides. “Only same brand” or “Only same category”: only products of the same brand or main category as the reference product.                                          | “Mixed”                                     |
| “Product type”             | “Off (as before)”, “Same type”, “Preferred (same group)”, “Matching types”. Only takes effect if product type detection is enabled for your index.                                                  | new templates “Same type”, older ones “Off” |
| “Prefer products in stock” | products in stock move up, out-of-stock products remain possible                                                                                                                                    | off (on in many presets)                    |
| “Exclude item group”       | Expert mode. InsightSearch always excludes variants of the reference product, this switch only takes effect with the older fallback method.                                                         | off                                         |
| “Disallow identical title” | Expert mode. Removes products whose title exactly matches the reference product.                                                                                                                    | on                                          |
| “Exclude cart products”    | Expert mode. Also excludes products already in the cart (including variants) on product pages and in Shopping Experiences. Cart and off-canvas always exclude them. Stays usable with shop sources. | off                                         |
| “Minimum similarity score” | Expert mode. Quality threshold from 0 to 1, 0 = off. Fewer products than the limit may appear.                                                                                                      | 0 (off)                                     |
| Rule builder (“Filters”)   | Expert mode, from plan Expert. Your own rules on product fields.                                                                                                                                    | no rules                                    |

{% hint style="info" %}
Product type detection is a beta feature. InsightSearch enables it for your index. Until it is enabled, every setting behaves like “Off”.
{% endhint %}

Details with examples: [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).

## 3. Weighting

The weighting is always visible. It decides the order of the products that remain after the filters. Each weight acts as a share of the sum of all weights, and the bar “Share of similarity” shows the distribution.

### Profiles

Next to “Profile:” you pick a ready-made weighting. A profile resets all nine weights, your own values are lost (confirmation “Replace custom weighting?”).

| Profile                   | Purpose                                                           |
| ------------------------- | ----------------------------------------------------------------- |
| “Balanced (default)”      | InsightSearch defaults, the best start for most shops             |
| “Prefer same brand”       | the same brand counts much more, other brands remain possible     |
| “Same properties”         | colour, material, size and attributes count most                  |
| “Similar content (AI)”    | content similarity counts most, needs the finished AI preparation |
| “Shopper behaviour first” | viewing and buying together counts most, needs enough data        |
| “Same price level”        | a similar price counts most                                       |

If no profile matches, you see “Custom weighting (no profile matches exactly).” If data for a profile is still missing, it carries a warning sign.

### The nine sliders

All sliders range from 0 to 1 in steps of 0.05.

| Slider              | What counts                                       | Default (share) |
| ------------------- | ------------------------------------------------- | --------------- |
| “Category”          | the same or a close category                      | 0.35 (≈ 21 %)   |
| “Brand”             | the same brand                                    | 0.35 (≈ 21 %)   |
| “Content (AI)”      | content similarity based on title and description | 0.3 (≈ 18 %)    |
| “Price”             | a similar price level                             | 0.2 (≈ 12 %)    |
| “Shopper behaviour” | viewed, added to cart or bought together          | 0.2 (≈ 12 %)    |
| “Popularity”        | generally popular products                        | 0.1 (≈ 6 %)     |
| “Context”           | colour, material, gender, size and main category  | 0.1 (≈ 6 %)     |
| “Attributes”        | matching product attributes                       | 0.05 (≈ 3 %)    |
| “Tags”              | matching tags                                     | 0.05 (≈ 3 %)    |

### Fine-tuning (expert mode)

| Field                       | Effect                                                         | Range               |
| --------------------------- | -------------------------------------------------------------- | ------------------- |
| “Prefer same category”      | switch, gives higher weight to matches from the same category  | on/off, default off |
| “Max. price deviation”      | price band: 0.35 = up to ±35 % counts as price-similar         | 0.05 to 3           |
| “Category bonus”            | favours the same category (only with “Prefer same category”)   | 0 to 1              |
| “Brand penalty”             | more brand variety                                             | 0 to 1              |
| “Category penalty internal” | more variety within a category                                 | 0 to 1              |
| “Diversity”                 | only in mode “Mixed”: 1 = similarity only, 0 = maximum variety | 0 to 1              |

The button “Copy for sandbox” copies the values relevant for the calculation to the clipboard. Details: [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).

## 4. Boosters

This card only appears in expert mode. Boosters give a product extra points when a condition matches, regardless of how similar it is.

| Field            | Effect                                           | Range                    |
| ---------------- | ------------------------------------------------ | ------------------------ |
| “Brand boost”    | strengthens products of the same brand           | 0.1 to 10, 1 = no effect |
| “Category boost” | strengthens products of the same category        | 0.1 to 10, 1 = no effect |
| “Path boost”     | strengthens products from the same category path | 0.1 to 10, 1 = no effect |

You cannot create your own booster rules, for example for margin. The only other preference is the switch “Prefer products in stock” under “2. Filters”.

## 5. Display

| Field                     | Effect                                                                                                                    | Default       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- |
| “Limit”                   | Required. Maximum number of recommendations shown, 1 to 50.                                                               | 6             |
| “Button action”           | “Show details” opens the product page, “Add to cart” adds the product directly to the cart, “Details + cart” offers both. | “Add to cart” |
| “Fallback threshold”      | The fallback is used as soon as the number of loaded products is less than or equal to this value (0 to 50).              | 0             |
| “Fallback type”           | “No fallback” (the block may stay empty), “Other template”, “Fixed products”, “Dynamic product stream”                    | “No fallback” |
| “Fallback template”       | with “Other template”: the template that steps in                                                                         | empty         |
| “Fallback products”       | with “Fixed products”: these products appear when the fallback is used                                                    | empty         |
| “Fallback product stream” | with “Dynamic product stream”: the product stream that steps in                                                           | empty         |

**Example:** “Limit” 6, “Fallback threshold” 3, “Fallback type” “Other template” with a bestseller template. If the template finds only 2 products, the block shows the bestsellers instead.

{% hint style="warning" %}
A fallback template whose type is not included in your plan is not used. Choose a type from your plan as the fallback.
{% endhint %}

A block without products is not shown in the shop. Without a fallback, a block can therefore be missing on some pages.

## Saving and when changes apply

Saved changes apply from the next recommendation the shop requests. Cached Shopping Experience pages that use this template are discarded automatically when you save. See [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)

## Read more

{% content-ref url="/pages/bOsKhfEoKG9Mcf9pbuHy" %}
[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)
{% 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/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 %}


---

# 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/recommendation-templates.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.
