Skip to main content

​
Promoting products

When a priority rule uses descending direction, it promotes matching products to the top of results. Priority rules are always applied first as hard overrides, so promoted products appear at the top regardless of their position in the expression list. Example: Promote Nike products 
1. Priority Rule: vendor equals "Nike"
2. Sort by: Sales (7d) - Descending
Result:
  • All Nike products appear first (regardless of sales)
  • Within Nike products, sorted by sales
  • Non-Nike products appear after, sorted by sales
Use case: Feature a specific brand or collection at the top of search results while maintaining secondary sorting for both groups.

​
Promoting multiple values

When using in or notIn operators, you can specify multiple values in a single priority rule. This is available in the UI when you select these operators, which enable multi-select functionality. Example: Promote multiple brands 
1. Priority Rule: vendor in ["Nike", "Adidas", "Puma"]
2. Sort by: Sales (7d) - Descending
Result:
  • All Nike, Adidas, and Puma products appear first
  • Within promoted brands, sorted by sales
  • Other brands appear after, sorted by sales
Use case: Feature multiple preferred brands or vendors without creating separate priority rules for each one. Example: Boost multiple product tags 
1. Priority Rule: tags in ["featured", "bestseller", "staff-pick"]
2. Sort by: Price - Ascending
Result:
  • Products with any of the specified tags appear first
  • Within tagged products, sorted by price
  • Untagged products appear after, sorted by price
Use case: Promote products with any of several promotional tags in a single rule. Example: Exclude price ranges 
1. Sort by: Sales (7d) - Descending
2. Priority Rule: variant_price not between [100, 200]
Result:
  • Products priced outside 100−100-200 appear first, sorted by sales
  • Products priced between 100−100-200 appear at the bottom
Use case: Demote products in specific price ranges that don’t align with current campaign goals. Example: Promote products with attributes set 
1. Priority Rule: compare_at_price is not null
2. Sort by: Discount Percentage - Descending
Result:
  • Products on sale (with compare-at price) appear first, sorted by discount
  • Regular-priced products appear after
Use case: Feature sale items by checking if the compare-at price attribute has been set.

​
Demoting products

When a priority rule uses ascending direction, it demotes matching products to the bottom of results. Priority rules are always applied first as hard overrides, so demoted products are pushed to the bottom regardless of their position in the expression list. Example: Demote out-of-stock products 
1. Sort by: Sales (7d) - Descending
2. Priority Rule: inventory_quantity equals 0
Result:
  • In-stock products appear first, sorted by sales
  • Out-of-stock products appear at the bottom
Use case: Push less desirable products (out of stock, discontinued, low ratings) to the bottom while maintaining primary sort order for the rest. Demoted products are always pushed to the bottom, and the remaining sort expressions determine the ordering within the non-demoted group.

​
Soft demotion examples

Example: Soft demote clearance items in search 
1. Sort by: Relevance Score - Descending
2. Priority Rule: tags contains "clearance" (Soft Demotion: enabled, Threshold: 0.6)
Result:
  • Clearance items above the 0.6 threshold are immune to demotion and maintain their relevance-based position
  • Clearance items below the 0.6 threshold receive proportional demotion based on how far below the threshold they are
  • Non-clearance items maintain their relevance-based ranking
Use case: Reduce visibility of clearance items without completely hiding the best matches when they’re highly relevant to what the customer is searching for. Example: Hard demote vs. soft demote vendor Hard demotion (default): 
1. Sort by: Relevance Score - Descending
2. Priority Rule: vendor equals "Budget Brand"
Result: All “Budget Brand” products appear at the bottom, regardless of how well they match the search query. Soft demotion with default threshold: 
1. Sort by: Relevance Score - Descending
2. Priority Rule: vendor equals "Budget Brand" (Soft Demotion: enabled, Threshold: 0.5)
Result:
  • “Budget Brand” products above the 0.5 threshold are immune to demotion and maintain their relevance position
  • “Budget Brand” products below the 0.5 threshold receive proportional demotion
  • Non-”Budget Brand” products maintain their relevance-based ranking
Soft demotion with high threshold: 
1. Sort by: Relevance Score - Descending
2. Priority Rule: vendor equals "Budget Brand" (Soft Demotion: enabled, Threshold: 0.7)
Result: Only “Budget Brand” products above the 0.7 threshold are protected; more products receive demotion compared to the default threshold. Use case: Prefer premium brands while still showing budget options when they’re exactly what the customer is searching for. Adjust threshold based on how strict you want the protection to be.

​
Multiple priority rules

You can combine multiple priority rules to create sophisticated ranking logic: Example: Promote featured, demote out-of-stock 
1. Priority Rule: tags contains "featured"
2. Sort by: Sales (7d) - Descending
3. Priority Rule: inventory_quantity equals 0
Result:
  • Featured products appear first (promoted)
  • Regular in-stock products in the middle, sorted by sales
  • Out-of-stock products at the bottom (demoted)

​
Priority rules with limit

Priority rules support a limit parameter to control how many matching products are promoted or demoted: Example: Promote top 5 new arrivals 
1. Priority Rule: published_at > 7 days ago (limit: 5)
2. Sort by: Sales (7d) - Descending
Result:
  • Top 5 newest products appear first
  • Remaining products sorted by sales (including other new products beyond the limit)

​
See also