Add Rules
To build a rule, the first step is to use the rule editor to define the conditions in the shopper’s query text that trigger the associated events. Then, complete the rule details, test the results, and publish the rule.
Add a rule
- In the Admin, go to Marketing > SEO & Search > Live Search.
- Set the Scope to identify the store view where the rule applies.
- Click the Search Merchandising workspace.
- Click Add rule to launch the rule editor.
Rule type
A Search query is where you define a specific search term, conditions and ranking types.
A Default rule can be set which is applied to all queries, unless a more specific search query is defined. Only one default rule can be set and it cannot contain any conditions. If you select Default, the Conditions interface is not displayed.
Choose the default Intelligent ranking type and any manual rankings you want applied to all default searches. Manual rankings are always applied.
Conditions
Conditions are the requirements to trigger an event. A rule can have up to ten conditions and 25 events. A default rule cannot have any conditions.
Single condition
-
Under Build your rule, select the Condition to be met, and follow the instructions to complete the statement.
- Search query contains - Enter the string of text that must be in the shopper’s query. The Match setting determines the degree to which the shopper’s query matches the catalog. Options:
Any - Any part of the shopper’s query text can match the condition.
All - All of the shopper’s query must match the condition. - Search query is - Enter a string of text that exactly matches the shopper’s query. For example: “yoga pants”. Rules with
Search query isand MatchAllcan have only one condition. - Search query starts with - Enter a character or string of text that must be at the beginning of the shopper’s query.
- Search query ends with - Enter a character or string of text that must be at the end of the shopper’s query.
The results appear immediately in the Test your rule pane and are numbered by priority. You can use the Results per row slider in the upper right to change the number of products in each row.
- Search query contains - Enter the string of text that must be in the shopper’s query. The Match setting determines the degree to which the shopper’s query matches the catalog. Options:
-
To test other queries, change the query text in the Test your rule search box and press Return.
Initially, the test pane renders the query from the Conditions search box. But now it is rendering the query from the test query box. The test pane renders only one query at a time. -
If you like the result, update the text in the Conditions search box. Then, click anywhere on the page to update the results in the test pane.
-
To build a simple rule with one condition, go to Step 3: Add events.
Multiple conditions
-
To build a rule with multiple conditions, click Add condition.
A rule can have up to ten conditions. The logical operator that joins two conditions is based on the current Match setting. By default, Match isAlland the logical operator isAND. -
Select the second condition and enter the required query text.
-
To change the logic of the rule, change the Match setting to determine how closely the shopper’s search criteria must match the query condition. Set Match to one of the following:
- Any - (Default) All logical operators in the rule are set to
ORand the results appear in the test pane. - All - All logical operators in the rule are set to
ANDand the results appear in the test pane.
The Match value determines the logical operator that is used to join multiple conditions. Changing the Match setting changes all logical operators in the rule. It is not possible to combine
ANDandORin the same rule.In this example, rather than searching for “yoga pants”, there are two separate queries that search for “yoga” or “pants”. This rule is less specific and is triggered more often in the storefront than the other.
- Any - (Default) All logical operators in the rule are set to
-
To add another condition, click Add condition and repeat the process.
Intelligent ranking intelligent-ranking
Intelligent ranking combines user behaviors and site statistics to determine product ranking.
Store owners can set up the following types of ranking strategies:
- Most purchased: This ranks products by total purchases per SKU in the previous 7 days.
- Most added to cart - Ranks in order of total “Add to Cart” activities in the previous 7 days.
- Most viewed: Ranks the total views per SKU in the previous 7 days.
- Recommended for you - Uses the
viewed-vieweddata point - Shoppers who viewed this SKU also looked at these other SKUs. - Trending: Looks back at page view events over the past 72 hours for background events and 24 hours for foreground events.
- None: Products are ordered by Relevance.
Select the type of strategy for the rule. The Test your rule window displays the expected results.
Intelligent ranking boost intelligent-ranking-boost
For Recommended for you, Most viewed, Most purchased, Most added to cart, and Trending, the editor shows Intelligent Ranking Boost (the boost factor). It is not used when you select None.
Use this control to balance how strongly behavioral signals influence ordering relative to textual relevance on search, and relative to other ranking signals on category pages and default listings. The boost is available for search query rules, default rules, and category merchandising rules; each rule stores its own value.
5 (equivalent to the previous fixed behavioral multiplier).1 (gentler behavioral influence) through 100 (stronger influence).When to raise or lower the boost
- Raise the boost when strategies such as Most viewed should surface high-engagement SKUs more aggressively for ambiguous or broad queries, without hand-pinning every slot.
- Lower the boost when you want textual match quality to drive the list more strictly and behavioral data should nudge order only slightly.
When to use manual ranking instead
Use pin, boost, or bury when you need specific products in exact positions or guaranteed visibility regardless of catalog-wide signals. Intelligent Ranking Boost tunes a global behavioral weight for that rule; it does not replace SKU-level control.
How intelligent ranking scoring works (search)
For search rules (and the test query in the rule editor), intelligent ranking determines the final product order by combining two key factors: textual relevance and behavioral signals. Understanding how these factors interact helps you set realistic expectations for your search results.
Scoring components:
-
Textual relevance: The dominant factor in scoring. This measures how well a product’s name, description, and attributes match the search query. The text relevance score is unbounded (has no specific upper limit) and is influenced by factors like:
- Frequency of occurrence of matching words.
- Length (in words) of product names/descriptions.
-
Behavioral signals: A bounded boost applied on top of the text relevance score. When you select an intelligent ranking strategy like “Most viewed” or “Most purchased,” products with higher behavioral signals receive a larger relative weight. The strength of that weight is controlled by Intelligent Ranking Boost (see Intelligent ranking boost); the boost remains bounded, but you can increase how much it shifts ordering.
Why the most viewed product might not appear first:
Textual relevance often dominates ranking because its score is unbounded, while behavioral influence is capped by the boost model. Products with very strong text matches can still outrank SKUs with higher engagement unless you increase Intelligent Ranking Boost for that rule. Even at higher boost values, an extreme text relevance gap may not fully invert the list, as text match quality remains a primary driver. Always validate results in Test your rule for your target queries.
Example:
A merchant uses the “Most viewed” intelligent ranking strategy and searches for candle. They expect product SKU YAN-K-E-512 to appear at the top of results because it has the highest view count. However, other products rank higher:
-
Texas Candle (1st position): Has a shorter, cleaner product name that creates a very high text relevance score. Even though it has fewer views than YAN-K-E-512, its superior text match outweighs the behavioral boost.
-
YAN-K-E-512 (lower position): Despite having the highest view percentile in the “Most viewed” behavioral data, its complex SKU-based name generates a lower text relevance score. At the default Intelligent Ranking Boost (
5), behavioral influence may not be enough to overcome that text gap. Increasing the boost can move YAN-K-E-512 higher among products that already match the query. YAN-K-E-512 must also match the query: at least one searchable attribute for that SKU must include candle, or it will not appear in results and the boost cannot apply.
Example (broad query):
For a query such as wood, several products can share similar textual relevance while view counts differ. With Most viewed selected, increasing Intelligent Ranking Boost makes the historically most-viewed relevant SKU more likely to surface above lighter matches. Lowering the boost keeps results closer to pure textual ordering.
See search rules to learn how to improve product findability using rules.
Caveats
-
Apostrophes and quotes in queries may lead to some minor issues with ranking and relevance in some languages.
-
To ensure the intelligent ranking works correctly, make sure that the Search Weight for any product attributes that are used for search or filtering (facets) is
5or less. To find this setting in the Commerce Admin:-
Select Stores > Attributes > Product.
-
Search for the attribute, such as “name”.
-
In the Attribute Information > Storefront Properties page, set the search weight to be less than or equal to
5.
-
Manual ranking
Manual Ranking (formerly referred to as Events) are actions that modify the search results when defined conditions are met. A single rule can have up to 25 events.
- Boost - Moves a product higher in the search results.
- Bury - Moves a SKU lower in the search results.
- Pin a product - Product is displayed in the selected “Position” on the page.
- Hide a product - Excludes a SKU from the search results.
The easiest way to pin a product is by drag and drop.
-
Click and drag a product in the Test pane. Drag and drop it at the desired position. The Product and Position fields are automatically populated in the Events pane.
You may also click the pin icon to pin a product to its current location. Use the ellipsis context menu to “Pin to top” or “Pin to bottom”.
Or events can be set manually:
-
Under Events, choose the Event to take place when the associated conditions are met.
For example, choose
Hide a product. Then, enter the name of the product that you want to hide. Products are suggested as you type. -
For multiple events, choose any other events that you want to trigger when conditions are met.
Additional details
The information that is entered here appears in the Rule Details panel.
-
Under Details, enter a Name for the rule. All rule names must be unique.
-
Enter a brief Description of the rule.
-
Enter the Start Date and End Date for the rule to be active or choose the dates from the calendar.
To select a range of dates, click the first date and drag to select the range.
Finalizing the rule
-
Examine the results of the rule in the test pane.
-
If the rule has multiple queries, test each one that might be affected by the rule.
-
When complete, click Save and publish.
The rule is added to the list in the Rules workspace.
note important IMPORTANT If the Save and publish button is greyed out, make sure you have entered all required information for the rule, including the rule name. -
Although active rules go into effect immediately, you might have to wait up to 15 minutes for the cached query results in the storefront to be refreshed.
Field descriptions
Conditions (if)
Logical operators
OR compares two conditions and meets the requirements to trigger an event if at least one condition is true.AND compares two conditions and meets the requirements to trigger an event if both conditions are true.Match operators
OR and returns the set of matching products.AND and returns the set of matching products.Manual ranking
Details
Intelligent ranking controls
5; allowed range 1–100. Applied at query time; rule preview matches live behavior for the configured rule.