You can trigger Promotion Rules for either Searches or Category pages. Enabling you to promote results when people search for specific terms, curate the order of results on your category pages, or automate the ordering of results on sales pages based on your business goals.
Promotion rules execute on top of search relevance settings. This means that promotion rules run for all search pipelines.
Promote items on category pages or searches


To execute a Promotion Rule, when a user searches for a particular term, select the Searches option.
Next up, specify the type of match for the query. Similar to , you can choose from several options to match a single phrase: is is not contains does not contain starts with ends with Or to match multiple phrases separated by commas. contains all contains any contains none of equals any equals none
Matching Searches
is star wars
Only matches exact searches for "star wars". It does not match "star wars episode I"
contains star wars
Matches all searches that contain the phrase "star wars". It does match "star wars episode I"
starts with star
Matches all searches starting with "star". For example, "star wars" and "star trek"
contains any luke, leia, han
Matches all searches that contain either the phrase "luke", "leia", or "han"

Category pages

Filters typically power category pages using specific fields. The name itself hints at one of the most common use-cases, categories. However, in e-commerce, category pages are often used to show products of specific brands, items on sale, or new arrivals. Each of those cases uses a different field to identify the category page and filter the items shown.
The main difference between Category pages and Searches is the field we are matching. For Searches, we always match on the search query field (q). However, as hinted at above, the field we want to match can vary for category pages.
Therefore, to set up a promotion for a category page, you will have to specify the field to match. Examples of the most common fields are:
  • category
  • collection
  • collection_id
  • brand
  • type
  • onSale
Specify the value you want to match when using a filter with this field. The available conditions will depend on the type of field. Numeric fields, for example, do not show the "contains" option.


Schedule a rule to be triggered only during a certain period. Common use-cases for specifying timeframes include:
  • Sale promotions on e-commerce sites
  • Temporary rules with fixed end dates
  • Time-bound rules to promote page during specific periods or events
    • Tax time
    • Holidays
    • New releases

Advanced settings

Promotion rules in the UI are currently limited to the above settings. However, since promotion conditions are powered by the same Filter expressions that are available for conditions in Search settings, you can create advanced rules via the API. For more details, refer to the Promotions API documentation