> 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/filters-and-rule-builder.md).

# Filters and rule builder

How mode, product type, stock switches and the rule builder decide which products a template may recommend at all.

Filters decide which products a template may recommend at all. They are strict: what a filter excludes does not come back, no matter how high the weighting. Use filters when certain products should never appear, for example other categories, out-of-stock items or cheaper alternatives when upselling. If you only want to move products up or down, [weighting](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/weighting-and-boosters.md) is the right tool.

All settings on this page are in the template, section “2. Filters”.

## What is always excluded

Some exclusions apply without you doing anything:

* the reference product itself, i.e. the product the recommendations are for,
* variants of the reference product, for example other colours or sizes of the same item,
* in the cart and the off-canvas cart, all products already in the cart, including their variants,
* only one variant per item, so the same jacket does not appear three times in different colours.

In addition, “Disallow identical title” is switched on by default. What applies to the current template is summed up in the box “In short: what this template filters” at the top of the section, with the line kinds “Filter”, “Exclusion”, “Preferred” and “Rules”.

## Mode: tie to brand or category

| Option               | Effect                                                           |
| -------------------- | ---------------------------------------------------------------- |
| “Mixed”              | Category and brand are not fixed, similarity decides. Default.   |
| “Only same brand”    | only products of the same brand as the reference product         |
| “Only same category” | only products of the same main category as the reference product |

Both tied modes need a reference product, i.e. a product page, the cart or a fixed product. If it is missing or has no brand or category, the mode is dropped. The preview shows this.

**Relax instead of empty:** if “Only same category” finds too few products, InsightSearch automatically adds the parent category. Matches from the exact category stay in front. The top-level category is not relaxed any further.

{% hint style="info" %}
Collection categories such as “Sale” or “New arrivals” distort comparisons by category. InsightSearch can exclude such categories for your index (ignored categories). They then count neither for “Only same category” nor for category similarity.
{% endhint %}

If you only want to prefer a brand or category rather than enforce it, leave the mode on “Mixed” and use the weighting profile “Prefer same brand” or the “Category” slider.

## Product type (beta)

The product type is a detected classification such as “mug” or “T-shirt”. It is more precise than the category because it also separates products in mixed categories.

| Option                   | Effect                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------- |
| “Off (as before)”        | The product type plays no role.                                                                       |
| “Same type”              | only products of the same type, for example only mugs for a mug                                       |
| “Preferred (same group)” | products of the same type group, same type first. Others remain possible.                             |
| “Matching types”         | only types stored for the source type under “Goes with” in the AI section, for example lids for a mug |

If the source product has no type, InsightSearch filters by the main category instead. With too few hits it relaxes step by step: from the type to the type group, then to the main category.

{% hint style="warning" %}
Product type detection is a beta feature and is enabled for your index by InsightSearch. Without it, every option behaves like “Off”.
{% endhint %}

## Stock: prefer or hide

There are two ways, and they work differently:

| Way                            | Where                  | Effect                                                            |
| ------------------------------ | ---------------------- | ----------------------------------------------------------------- |
| “Prefer products in stock”     | switch in “2. Filters” | Products in stock move up. Out-of-stock products remain possible. |
| Building block “Only in stock” | rule builder           | Out-of-stock products are hidden completely.                      |

Whether a product is available comes from Shopware (clearance sale, minimum purchase). A parent product counts as available as soon as one of its variants is available. A stock change takes effect once InsightSearch has read in the product data again.

## Further switches in expert mode

| Switch or field            | Effect                                                                                                                                       | Default |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| “Disallow identical title” | removes products whose title exactly matches the reference product                                                                           | on      |
| “Exclude cart products”    | also excludes cart products on product pages and in Shopping Experiences                                                                     | off     |
| “Exclude item group”       | only takes effect with the older fallback method, variants are excluded anyway                                                               | off     |
| “Minimum similarity score” | quality threshold from 0 to 1. Products below it are dropped, fewer than the limit may appear. Boosters do not count towards this threshold. | 0 (off) |

## The rule builder

{% hint style="info" %}
Available from plan Expert. The rule builder appears in section “2. Filters” under the heading “Filters” as soon as expert mode is on.
{% endhint %}

Rules restrict which products may be recommended. You can use the fields from the “Data fields” section. If a field is missing, activate it under “Edit data fields” and read in the product data once. It is then available here. See [Data fields](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/data-fields.md).

### Building blocks for a quick start

Next to “Building blocks:” you add common rules with one click. A building block only appears if the required fields exist in your product data.

| Building block               | Effect                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| “Only in stock”              | only products that are currently available                                           |
| “Similar price (±20 %)”      | price at most 20 % below and at most 20 % above the reference product                |
| “Not cheaper than reference” | only products costing at least as much as the reference product. Good for upselling. |
| “Same colour as reference”   | only products with the same colour                                                   |
| “Other brand than reference” | only products of other brands. Good for alternatives.                                |

If rules already exist, the building block puts them into their own group and applies in addition (AND). If a building block is already set, the form tells you instead of adding it twice.

### Groups and rules

Rules live in groups. Each group has a connector:

* “AND (all match)”: every rule in the group must match.
* “OR (any match)”: one matching rule is enough.
* “Negate (NOT)”: products that satisfy the group are excluded instead of allowed.

Use “Add rule” and “Add group” to build conditions, “Duplicate” to copy and “Remove” to delete. Groups can be nested up to three levels deep, for example (brand = X AND price less than 50) OR category = Sale.

Each rule consists of these fields:

| Field                              | Meaning                                                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| “Attribute”                        | the product field to filter on, for example “Price”, “Brand”, “Category”, “Availability”                              |
| “Condition”                        | how the value is compared (see the table below)                                                                       |
| “Value”                            | the value to compare with. Separate multiple values with commas. Yes/no fields and categories are chosen from a list. |
| “Unit”                             | for offsets, “absolute” or “percent”                                                                                  |
| “Days”                             | for date conditions, the number of days relative to today                                                             |
| “Active”                           | Disabled rules stay saved but are ignored.                                                                            |
| “Use reference product value”      | compares against the value of the reference product instead of a fixed value                                          |
| “Reference attribute” and “Offset” | which field of the reference product applies and how far it may deviate, for example price +10                        |

A rule without a value is ignored, and the form shows “This filter has no value and will be ignored.”

### Conditions

| Condition                                | Meaning                                    |
| ---------------------------------------- | ------------------------------------------ |
| “is” / “is not”                          | exactly equal or not equal to the value    |
| “greater than” / “at least”              | greater, or greater than or equal          |
| “less than” / “at most”                  | less, or less than or equal                |
| “between”                                | lies between two values                    |
| “before” / “after”                       | lies before or after a date                |
| “contains” / “starts with” / “ends with” | text comparison                            |
| “is one of” / “is none of”               | matches at least one or none of the values |
| “contains all of”                        | contains all given values                  |
| “is set” / “is empty”                    | the field has a value or has none          |
| “within the last” / “older than”         | relative date filters in days              |

Which conditions a field offers depends on its type in the “Data fields” section. An offset to the reference product is possible with the greater-than and less-than conditions.

### Matches per rule

Next to each rule the builder shows its effect: “matches … products on its own”, “excludes … products” or “excludes nothing here”. If it says “matches no product: check value and condition”, the rule leaves nothing. A typo in the value is a common cause.

## Types without a reference product

With types such as “Bestsellers”, “Trending now” or “Recently viewed” there is often no product the recommendations are for. Exclusions, the stock check and fixed rules still apply. The mode and rules using “Use reference product value” only apply when a reference product exists, for example on a product page. Otherwise the preview reports that the reference value could not be resolved.

## Practical examples

**Only matching accessories:** mode “Mixed”, “Product type” “Matching types” (if enabled), building block “Only in stock”.

**Upselling on the product page:** mode “Only same category”, building block “Not cheaper than reference”.

**Alternatives from other manufacturers:** mode “Mixed”, building block “Other brand than reference”, plus “Similar price (±20 %)”.

**Exclude a promotion category:** new group with “Negate (NOT)”, containing the rule “Category” “is one of” and the promotion category.

**Only products of one margin class:** transfer your own custom field, for example “margin class”, via the data fields and filter on it. This is a strict filter, not a preference.

## When too little remains

1. Check the match counts per rule and the [preview](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/preview-and-sandbox.md).
2. Relax the strictest rule or set the mode to “Mixed”.
3. Lower the “Minimum similarity score”.
4. Set a fallback under “5. Display” so the block never stays empty.

InsightSearch never fills up without filters: stock, rules and exclusions also apply when relaxing.

## Read more

{% 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/8G9wQ55abqkazf3FuGK0" %}
[Data fields](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/data-fields.md)
{% endcontent-ref %}

{% content-ref url="/pages/A5tmmG01QN0sNwbBOlS6" %}
[How recommendations work](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/how-recommendations-work.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/filters-and-rule-builder.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.
