Search Rules

​

Overview

Search Rules provide a powerful way to customize how search requests are processed based on specific conditions. Unlike static search configurations, Search Rules evaluate targeting conditions at query time and apply modifications dynamically, giving you fine-grained control over the search experience.

​

How Search Rules Work

When a search request is received, the system evaluates all enabled Search Rules in priority order. Rules that match the targeting conditions have their actions applied to the request before execution. This allows you to transform queries, inject filters, adjust tuning parameters, or override sort orders based on the context of each search.

​

Request Types

Search Rules can be configured to apply to specific types of search requests: All Search Types applies the rule to every search request regardless of type. Text Search targets traditional keyword-based searches. Image Search applies to visual search requests where users search by uploading an image. Similar Search targets requests for finding products similar to a specific item. Browse applies to collection browsing requests. You can select multiple request types for a single rule, allowing flexible targeting across different discovery experiences.

​

Targeting Conditions

Targeting conditions determine when a Search Rule should be applied. Conditions can be combined using AND/OR logic for complex matching scenarios. Search Query matches against the user’s search terms. You can use operators like contains, equals, starts with, or ends with to match specific query patterns. Collection Handle targets searches within specific collections. This is particularly useful for applying different search behaviors to different product categories. Query Product Type and Query Product Vendor allow targeting based on the types of products or vendors in your catalog, enabling category-specific or brand-specific search modifications.

​

Contextual Targeting

Search Rules now support contextual targeting conditions, allowing you to create rules that respond to the shopper’s environment and behavior. These conditions use dot notation to access nested contextual data passed with each search request. Shopping Channel (context.shoppingChannel) targets based on where the customer is browsing. Values include web for desktop/mobile web browsers and app for mobile app experiences (automatically detected from request headers for Tapcart, Fuego, and Canvas integrations). Geo Location targets based on the customer’s geographic location:

• context.geo.country - Two-letter country code (e.g., “US”, “CA”, “GB”)
• context.geo.province - State or province
• context.geo.city - City name

Customer Data targets based on customer account status and purchase history:

• context.customer.signedIn - Boolean indicating if customer is logged in
• context.customer.returning - Boolean indicating if customer has previous orders
• context.customer.numberOfOrders - Total number of orders placed
• context.customer.totalSpent - Total amount spent across all orders
• context.customer.averageOrderValue - Average order value
• context.customer.daysSinceLastOrder - Days since most recent order
• context.customer.daysSinceOldestOrder - Days since first order
• context.customer.daysBetweenOrders - Average days between orders

Marketing Parameters targets based on UTM parameters and traffic source:

• context.marketing.source - UTM source (e.g., “google”, “facebook”, “email”)
• context.marketing.medium - UTM medium (e.g., “cpc”, “organic”, “social”)
• context.marketing.campaign - UTM campaign name
• context.marketing.term - UTM term (search keywords)

​

Use Cases

Channel-specific filtering: Create a rule with context.shoppingChannel != web to hide web-only products from mobile app users, or boost app-exclusive items when browsing through your mobile app. Geographic merchandising: Target customers in specific regions with context.geo.country = US to promote products available only in certain markets, or adjust search relevance for region-specific preferences. Personalized search for signed-in customers: Use context.customer.signedIn = true to boost previously purchased product types or show VIP-exclusive items to high-value customers based on context.customer.totalSpent. Campaign-specific search behavior: Target traffic from specific marketing campaigns with context.marketing.source = google and context.marketing.campaign = summer-sale to automatically filter results to sale items or boost promoted products. Combined contextual conditions: Layer multiple contextual conditions using AND/OR logic. For example, target mobile app users in the US who are signed in: context.shoppingChannel = app AND context.geo.country = US AND context.customer.signedIn = true.

​

Action Types

Each Search Rule can have one or more actions that modify the search request:

​

Replace Query

Completely replaces the user’s search query with a different query. Use this when you want to redirect searches for specific terms to more relevant alternatives.

​

Modify Query

Adjusts the search query without fully replacing it. Modification options include appending text to the end of the query, prepending text to the beginning, or replacing specific words within the query with alternatives.

​

Add Filter Group

Injects additional filters into the search request. This allows you to automatically narrow results based on the targeting conditions without the user explicitly selecting filters.

​

Modify Tuning Parameters

Adjusts the search tuning parameters for matched requests. You can modify the textual weight (balance between keyword and semantic matching), visual weight (influence of image similarity), minimum match threshold, and multiple factor settings.

​

Override Sort Order

Forces a specific sort order for matched search requests, overriding the default or user-selected sorting.

​

Priority System

Search Rules use a priority system where lower numbers indicate higher priority. When multiple rules match a request, they are applied in priority order. This allows you to create layered rule sets where more specific rules take precedence over general ones.

​

Best Practices

When creating Search Rules, start with broad rules and refine based on search analytics. Use the priority system to layer general rules with specific overrides. Test rules thoroughly using the search evaluation tools before enabling them in production. Monitor search performance after enabling new rules to ensure they improve the customer experience. Consider using Search Rules for common scenarios like redirecting misspellings to correct terms, boosting seasonal or promotional content, applying category-specific tuning parameters, and filtering out irrelevant results for specific query patterns.

​

See also

• Configure search behavior
• Test text search
• User intent processing