> 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/search-intelligent-and-ai-optimized/search-term-rules.md).

# Search term rules

Define what customers see for individual search terms, with pinning, hiding, boosting and demoting, redirects and banners.

With search term rules you define what your customers see for individual search terms. A rule reads like a sentence: when a customer searches for "grill", three promotional grills appear at the top. You need rules when the automatic order does not fit your goal for a term, for example for promotions, for terms with info pages, or for products that should not appear for a term.

You find the rules in the plugin dashboard under **Products** in the tab **Rules**. Three buttons switch the sub-area: "Lost opportunities" (start here), "Rules" and "Editor".

{% hint style="info" %}
Search term rules are an add-on that you unlock via Shopware. If it is locked for your shop, a note at the top says that saved rules are kept and take effect after unlocking. The button "Unlock now" opens the purchase in Shopware. Until then, rules have no effect in the search.
{% endhint %}

## What a rule can do

| Action         | Effect                                                       |
| -------------- | ------------------------------------------------------------ |
| "Pin"          | Selected products appear at the very top.                    |
| "Hide"         | Selected products do not appear for this term.               |
| "Boost/Demote" | Manufacturers, categories or properties move up or down.     |
| "Redirect"     | Whoever submits the term lands directly on a target page.    |
| "Banner"       | A shopping experience appears as a banner above the results. |

You can combine several actions in one rule. At least one action must be set.

## Create a rule, step by step

1. Open **Products** → tab **Rules** → **Rules** and click "New rule". Alternatively, start in the "Editor", or in "Lost opportunities" with "Pin products". The term is then already filled in.
2. In the block "When a customer searches for …" enter the search terms, one per line or separated by commas, for example "grill, gas grill". Under "Term must" choose: "be searched exactly like this (exact)" or "appear in the search (contains)".
3. Optionally set "Valid from" and "Valid until" under "Set time period (optional)", with date and time in shop time. If a field stays empty, the period has no start or no end. The end must be after the start.
4. In the block "Then the search does …" choose the actions via "+ Add action …".
5. In the block "General" you optionally enter a "Name" (only for recognition, empty = first search term) and the "Priority". The switch "Rule active" turns the rule on or off.
6. Click "Save". Only then does the rule take effect in the shop.

After saving you see: "Rule saved. It takes effect in the search after a few seconds, on the search results page after two minutes at the latest." "Back to list" leaves the editor. With unsaved changes the interface asks first.

### Terms and when they apply

* A rule holds at most 20 terms, each at most 100 characters.
* Upper and lower case, umlauts ("ä" equals "ae"), punctuation, hyphens and "&" (equals "and") do not matter.
* **"exact":** Only exactly this term triggers the rule.
* **"contains":** The term must appear as a whole word (or whole word sequence) in a longer search. "grill" applies to "grill accessories", but not to "gasgrill".
* The rule applies to the term the customer typed. This is also true when, at zero hits, the search loosens or corrects the term and still shows results.

## Pin hits

1. Find the product in the field "Search product: name or product number" (magnifier or Enter).
2. Click "Pin". In the editor you can also click the pin icon in the preview or drag the hit upward.
3. Change the order under "Order in the shop" with "Move up one". "×" removes a product.

Pinned products appear at the very top, however the search would otherwise sort. Up to 24 products are possible. Variants count as one product.

Pinning only applies when sorting by relevance. If the customer sorts themselves, for example by price, or filters the product out, pinning does not apply. When paging, pinned products only appear on the first pages.

## Hide hits

Find the product as for pinning and click "Hide" (in the editor also the eye icon). The product then does not appear for this search term. In the shop it stays unchanged, so in categories, on the product page and for other search terms.

Up to 100 products are possible per rule. If a product is pinned and hidden, hiding wins. The interface points this out.

## Boost or demote

Here you move whole groups of products, for example all products of one manufacturer.

1. Choose the action "Boost/Demote".
2. Under "Level, if all conditions apply" choose a level:

| Level | Effect        |
| ----- | ------------- |
| +3    | strongly up   |
| +2    | clearly up    |
| +1    | slightly up   |
| −1    | slightly down |
| −2    | clearly down  |
| −3    | strongly down |

3. Define the condition: choose the attribute under "Choose attribute" (for example "Manufacturer" or a filter group such as category or color), the operator "is" or "is one of" (values separated by commas) and the value. The suggestion list comes from your filter values.
4. With "+ Condition (AND)" you add more conditions. All must apply.
5. With "Add level" you create another entry, with its own level and conditions.

Example: for "cordless screwdriver", the brand Bosch is boosted by +2 and the category Accessories is demoted by −2.

The level moves products within the matching hits. It does not bring products into the list that do not fit the search term anyway. Conditions the search cannot resolve (for example an unknown attribute) make the whole entry ineffective. It is not silently widened.

## Redirect

For the action "Redirect", enter a target, for example `/shipping` or a full address. Whoever enters "shipping" and submits the search (Enter or search button) lands directly on your shipping page. While typing, the search overlay keeps showing normal hits. The redirect works in the search overlay and on the search results page.

Allowed targets:

* Paths in your own shop (they start with "/").
* Addresses on the domains of your sales channels.
* Other domains only if they are listed in the plugin configuration under "Approved external domains for search term redirects", one domain per line.

Other targets are ignored and the search runs normally. When saving, the plugin checks the format (http or https, no credentials, no spaces). Otherwise it reports: "The redirect target is invalid. Allowed are paths such as /offer or http(s) addresses."

If two rules with equal priority send the same term to different targets, the rule list warns about the conflict.

## Banner

A banner is a shopping experience that appears above the search hits as soon as someone searches for a term of the rule. On the search results page it sits above the result list, in the search overlay above the product hits. This also applies when the search finds no products.

To create a banner:

1. In the Shopware admin, create a shopping experience of the type "Landing page" or "Shop page" under **Content → Shopping Experiences**.
2. Use only a slim block, for example an image banner or "Image with text", with a link if you like. No product listings and no tall sections.
3. Save the shopping experience. Assigning it to a category or sales channel is not necessary.
4. In the rule, choose the shopping experience under the action "Banner". "No banner" removes the banner again.
5. Save the rule.

If there is no suitable shopping experience yet, the interface points this out. If a shopping experience is deleted later, the spot stays empty. The rule list then shows that the banner page no longer exists. With "Valid from" and "Valid until" you control banners over time.

## The editor with before and after

In the "Editor", the form is on the left and the preview on the right. Enter a "Search term for the preview" and click "Preview". The column "With rule" shows what your customers see with the rule, the column "Without rules" shows the normal result for comparison. If the preview term does not match the terms of the rule, a note appears there.

* Drag hits in "With rule" upward with drag and drop to pin them.
* The pin icon pins or unpins, the eye icon hides.
* Small labels explain each hit, for example "pinned #1", "+2 Manufacturer: Bosch", "Text" (search term found in the product) or "AI similarity" (similar in content).
* Notes above the preview show a redirect, a banner (only with its name, not as an image) or the automatic rescue at zero hits.

## Several rules, priority and status

The "Rules" list shows all rules with name, terms, match type, actions, period and status. The search field "Search rules" helps you find a rule quickly. Each rule has "Edit", "Duplicate" (the copy is inactive at first and named "… (copy)") and "Delete".

| Status    | Meaning                                        |
| --------- | ---------------------------------------------- |
| active    | The rule is in effect now.                     |
| scheduled | The period starts later.                       |
| expired   | The period is over.                            |
| inactive  | The rule is switched off with the "On" switch. |

With the "On" switch you take a rule out of the search temporarily without deleting it.

### Priority

The "Priority" is a number from −1000 to 1000, default 0. If several rules match the same term:

* The higher priority wins. On a tie, "exact" comes before "contains", then the older rule.
* Hiding and boosting/demoting of all matching rules work together.
* Pinned products are appended in this order, at most 24.
* Redirect and banner only come from the strongest rule.

The list warns about contradictions, for example "Pinned and hidden at the same time", or when pinned products cannot be found.

## Limits at a glance

| Setting                                     | Limit                               |
| ------------------------------------------- | ----------------------------------- |
| Active rules per search index (data source) | 200                                 |
| Terms per rule                              | 20, each at most 100 characters     |
| Pinned products per rule                    | 24                                  |
| Hidden products per rule                    | 100                                 |
| Level entries per rule                      | 10, each with at most 10 conditions |
| Name                                        | at most 191 characters              |
| Redirect target                             | at most 2048 characters             |
| Priority                                    | −1000 to 1000                       |

When 200 active rules are reached, deactivate a rule first.

## When rules take effect

Pinning, hiding and boosting/demoting take effect in the search after a few seconds, on the search results page after two minutes at the latest. Rules with a period start and end on their own, with a delay of up to 5 minutes.

## Lost opportunities

The "Lost opportunities" list shows search terms where customers do not find what they are looking for. The terms with the most searches are at the top. You choose the period: 7, 30 (default) or 90 days. Next to it is the "Ø click rate in the search index" as a comparison value.

Three groups with at most 100 rows each:

| Group                    | Criterion                                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| "No results"             | Customers search for it and find nothing. Often a synonym is missing, or the term refers to an info page. |
| "Results, but no clicks" | At least 5 searches, results exist, but nobody clicks.                                                    |
| "Low click rate"         | At least 20 searches, at least one click, click rate below the average of the data source.                |

The columns show the term (in its most common spelling, with upper/lower case and umlaut variants merged), the number of searches, for "Low click rate" the click rate, and the "Possible revenue". Possible revenue is the number of searches times the average revenue per search in this data source. It is a rough estimate and not guaranteed extra revenue. If there was no revenue in the period, the field shows a dash.

For "No results", labels show whether the automatic rescue stepped in: "loosened" (with more typo tolerance there were results after all), "auto-corrected → …" (a similar term was searched) or "substitute products" (popular products were shown). The term stays in the list anyway, because your range does not serve it directly yet.

### One-click actions per row

* **"Create synonym":** A window "Synonym for …" opens in which you enter further terms separated by commas, for example "couch, sofa". For "auto-corrected", the correction is pre-filled. Message: "Synonym created. It takes effect in the search after a few seconds." More on the page [Synonyms](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/synonyms.md).
* **"Create redirect":** You enter a target. An active rule "Redirect: " with "exact" is created, which you can change later in the editor.
* **"Pin products":** Opens the editor with the term.
* **"Ignore for 90 days":** The row disappears from the list for 90 days. Nothing changes in the search. This suits typos, nonsense or terms you deliberately do not serve.
* **Magic wand icon:** A rule already exists for the term. A click opens it.

The link "Edit lost opportunities" in [Statistics](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/statistics.md) also leads straight to this list.

## Examples

**Promote an offer.** Term "grill", match "contains", three promotional grills pinned, a banner with a period until the end of August. Whoever searches "grill" or "grill accessories" sees the promotion at the top.

**Info page.** Term "shipping", exact, redirect to `/shipping`. Whoever submits "shipping" gets the shipping information instead of a product list.

**Hide a product for one term.** A product that regularly appears unwanted for a term, you hide for that term. In the rest of the shop it stays reachable.

**Prefer a brand.** Term "cordless screwdriver", manufacturer Bosch +2, Accessories −2.

## Tips

* Start with "Lost opportunities". The list shows where a rule helps most.
* Check every new rule in the "Editor" preview before saving.
* Use "Duplicate" for similar rules. The copy starts inactive, so you can adjust it in peace.
* Set periods for promotions so that rules end on their own.
* With sortings such as "Price", pinning does not apply. Therefore test with sorting by relevance.

## Read more

{% content-ref url="/pages/jaQ6nXm2Ug0rov8AO38O" %}
[Synonyms](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/synonyms.md)
{% endcontent-ref %}

{% content-ref url="/pages/s1zsa8FBn4f6VaJ5pRxJ" %}
[Products in the dashboard](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/products-in-the-dashboard.md)
{% endcontent-ref %}

{% content-ref url="/pages/HsFAOG9ZITzp3esXXRtx" %}
[Statistics](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/statistics.md)
{% endcontent-ref %}

{% content-ref url="/pages/ONADSPn6JKPHifT1E0iD" %}
[No results](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/no-results.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/search-intelligent-and-ai-optimized/search-term-rules.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.
