Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Soft boost is a sorting technique that lifts products matching specific conditions toward a target score. Unlike priority rules that cluster boosted products at the top, soft boost creates natural interleaving by lifting matched products only as much as needed to reach a target band. Soft boosts appear in the sort order editor with a Modifier badge and are visually grouped beneath the metric or attribute they modify. This tree layout makes it easy to see which expression each soft boost targets.

​
How soft boost works

Soft boost supports two modes: multiplicative (default) and additive. Each mode uses a different formula to lift products matching specific conditions.

​
Multiplicative mode (default)

Multiplicative mode applies a decaying multiplier to the base score. This produces natural interleaving because:
  • Products with low base scores get a larger relative boost (the exponential decay is minimal).
  • Products with high base scores get a smaller relative boost (the exponential decay is significant).
  • Non-matching products receive no boost (multiplier = 1).
Limitation: Multiplicative mode does not move products whose base value is zero. New arrivals with no sales remain stuck at the bottom regardless of boost settings — use additive mode for those cases.

​
Additive mode

Additive mode lifts matching products in value space toward a target score derived from the rest of the catalog. The target is the value at the chosen percentile of the base metric across all candidate products. For each matching product, a portion of the gap between its current score and the target is closed. A product whose base score is already above the target stays where it is — additive mode never demotes a matching product. The closer a product’s base score is to the target, the smaller the lift it receives, which prevents matched products from clustering at the top. Key advantages:
  • Works with zero base values: Products with no sales data can still be lifted effectively.
  • Value-space targeting: Control how high boosted products land relative to the rest of the catalog, expressed as a percentile of the base metric.
  • Gap-capped lift: Each match is lifted only as far as needed, so boosted products interleave naturally.
  • Ideal for new arrivals: Sprinkle new products with no performance history into established rankings.
  • Combines cleanly: Multiple additive boosts on the same metric add their lifts together for predictable layering.
When to use additive mode:
  • Boosting products with zero or near-zero base values (new arrivals, products with no sales).
  • Targeting a specific spot in the value distribution (for example, lifting matches to roughly the top quartile of sales).
  • Sprinkling new products into a best-selling sort order without clustering them at the top.
Additive mode was rewritten on 2026-05-02. It now interprets the percentile target in value space (a percentile of the base metric) instead of row positions, and boost strength now controls how much of the gap to the target is closed. Existing additive sort orders continue to work, but you may want to retune them — open each one in the editor, preview the result, and adjust Boost Strength and Percentile Target if the new ordering doesn’t match your intent.

​
Soft boost vs. priority rules

FeatureSoft boostPriority rules
Product distributionNatural interleaving throughout resultsHard override — forces products to top or bottom
Boost behaviorScore lift based on base value, capped at a targetHard promote/demote override applied first
Use caseSubtle promotion while maintaining organic rankingStrong promotion or demotion
ConfigurationBoost mode, strength, percentile/decay targetCondition and weight
Example: For a collection sorted by sales with a soft boost on tags = 'featured':
  • Priority Rule: All featured products appear first, regardless of sales
  • Soft Boost: Featured products with low sales get a significant boost, but high-selling non-featured products can still rank higher

​
Configuration parameters

​
Boost mode

Determines the formula used to boost matching products.
  • Options: multiplicative (default) or additive
  • Default: multiplicative
Multiplicative mode:
  • Multiplies the base value by a decaying boost factor.
  • Best for products with non-zero base values.
  • Uses Boost Strength and Decay Rate.
Additive mode:
  • Lifts matching products in value space toward a percentile-based target on the same metric.
  • Works even when the base value is 0.
  • Uses Boost Strength and Percentile Target. Decay rate is not used in additive mode.
  • Ideal for new arrivals or products with no performance data.

​
Boost strength

Controls how strongly matching products are lifted. The interpretation depends on the mode.
  • Range: 0 to 10
  • Default: 0.25
  • Recommended (multiplicative): 0.25 to 1.0 for subtle promotion, 1.0 to 2.0 for stronger effects.
  • Recommended (additive): 0.4 to 0.8 for most use cases.
Multiplicative mode: Amplitude of the multiplier applied to the base score. Higher values produce a stronger lift, especially for low-base-value products. Example impact (with Decay Rate = 100):
  • Product with base score 10 and Boost Strength 0.5: 10 × 1.409 = 14.09 (+41%).
  • Product with base score 100 and Boost Strength 0.5: 100 × 1.184 = 118.4 (+18%).
Additive mode: Fraction of the gap between the product’s base score and the percentile target that is closed for matched products.
  • 0 — no lift.
  • 0.5 — closes half of the gap to the target.
  • 1 — pulls the product exactly to the target value.
  • > 1 — overshoots the target. Use sparingly to avoid stacking matches above well-performing products.

​
Percentile target (additive mode only)

The target value for matched products in additive mode, expressed as a percentile of the base metric across the candidate set. A higher percentile lifts matched products further up the ranking.
  • Range: 0 to 100
  • Default: 50
  • Recommended: 50–75 for moderate visibility, 75–90 for high visibility.
  • Only used in additive mode.
Example impact when sorting by sales (descending):
  • Percentile Target 50: Matches are lifted toward the median sales value, blending into the middle of results.
  • Percentile Target 75: Matches are lifted toward the value at the 75th percentile, landing roughly in the top quartile.
  • Percentile Target 90: Matches are lifted toward the value at the 90th percentile, landing near the top.
A product whose base score is already above the percentile target stays where it is — additive mode never demotes a matching product.

​
Decay rate (multiplicative mode only)

Controls how quickly the boost diminishes as the base score increases. Higher values make the boost decay more slowly.
  • Range: 1 and above
  • Default: 100
  • Recommended: 50–200
  • Not used in additive mode.
Example impact (with Boost Strength = 0.5):
  • Decay Rate 50: Boost decays faster, more aggressive interleaving.
  • Decay Rate 200: Boost decays slower, boosted products stay higher longer.

​
Configuration requirements

Soft boost requires a metric or product attribute to modify. If no sortable expression exists in the sort order, an error dialog appears explaining that you need to add at least one metric or attribute first.
When you add a soft boost, it is automatically inserted above the last metric or attribute in the list so that it modifies that expression. You can reorder expressions after insertion if needed.

​
Example use cases

Boost products tagged as “featured” while maintaining sales-based ranking: 
1. Soft Boost: tags contains "featured" (Boost Mode: Multiplicative, Boost Strength: 0.5, Decay Rate: 100)
2. Sort by: Sales (7d) - Descending
Result: Featured products with moderate sales rank higher, but top-selling non-featured products can still win.

​
Boost multiple tags (multiplicative mode)

When using in or notIn operators, you can boost products matching any of multiple values. The UI enables multi-select when these operators are selected. 
1. Soft Boost: tags in ["featured", "bestseller", "trending"] (Boost Mode: Multiplicative, Boost Strength: 0.5, Decay Rate: 100)
2. Sort by: Sales (7d) - Descending
Result: Products with any of the specified tags receive a boost, creating natural interleaving based on their sales performance.

​
Exclude price ranges (multiplicative mode)

Use the not between operator to demote products in specific price ranges: 
1. Sort by: Sales (7d) - Descending
2. Soft Boost: variant_price not between [100, 200] (Boost Mode: Multiplicative, Boost Strength: -0.3, Decay Rate: 100)
Result: Products priced between 100−100-200 receive a negative boost, pushing them lower in results while maintaining natural ranking.

​
Boost products with specific attributes set

Use is not null to boost products that have specific attributes configured: 
1. Soft Boost: metafield.custom.featured_until is not null (Boost Mode: Multiplicative, Boost Strength: 0.5, Decay Rate: 100)
2. Sort by: Sales (7d) - Descending
Result: Products with a featured end date configured receive a boost, useful for time-sensitive promotions.

​
Sprinkle new arrivals into best sellers (additive mode)

Interleave new arrivals with zero sales into a best-selling sort order: 
1. Soft Boost: tags contains "new-arrival" (Boost Mode: Additive, Boost Strength: 0.6, Percentile Target: 75)
2. Sort by: Sales (7d) - Descending
Why additive mode? New arrivals have zero sales, so multiplicative mode would not move them. Additive mode lifts matching products toward the value at the 75th percentile of sales, so products with no sales history land in the upper portion of results. Result: New arrivals with zero sales are lifted toward roughly the top quartile of sales, naturally interleaved with established best sellers. As new products accumulate sales, their base score rises, the gap to the target shrinks, and their organic performance takes over. Use case: Perfect for fashion retailers launching seasonal collections, where new items need visibility before they have sales history. A Percentile Target of 75 with Boost Strength of 0.6 ensures new arrivals appear prominently without completely dominating the sort order.

​
Layer multiple additive boosts (additive mode)

Stack two or more additive boosts on the same metric to combine effects predictably. Lifts add together, so products matching multiple conditions land higher than products matching just one: 
1. Soft Boost: tags contains "new-arrival" (Boost Mode: Additive, Boost Strength: 0.5, Percentile Target: 60)
2. Soft Boost: tags contains "campaign-spring" (Boost Mode: Additive, Boost Strength: 0.4, Percentile Target: 80)
3. Sort by: Sales (7d) - Descending
Result: Products tagged with campaign-spring are lifted strongly toward the top, new arrivals are lifted into the upper-middle, and products tagged with both receive the combined lift. Non-matching best sellers remain competitive based on their organic sales.

​
Highlight recently published products (multiplicative mode)

Give recently published products a boost without completely overriding popularity: 
1. Soft Boost: published_at > 30 days ago (Boost Mode: Multiplicative, Boost Strength: 0.75, Decay Rate: 150)
2. Sort by: Total Sales - Descending
Result: New products get visibility while established bestsellers remain competitive.

​
Regional preference (multiplicative mode)

Boost products from specific vendors for certain markets: 
1. Soft Boost: vendor equals "Local Brand" (Boost Mode: Multiplicative, Boost Strength: 0.5, Decay Rate: 100)
2. Sort by: Relevance Score - Descending
Result: Local brand products rank higher while maintaining relevance-based ordering.

​
Works with other features

Soft boost integrates with other sort order capabilities:
  • Segmented Metrics: Apply soft boost to segmented metric scores for personalized boosting
  • Sequences: Soft boost respects product sequences when enabled
  • Multiple attributes: Chain multiple soft boosts or combine with weighted sorting

​
Best practices

  • Choose the right mode: Use multiplicative mode for products with non-zero base values, additive mode for products with zero or near-zero values (like new arrivals).
  • Start with sensible defaults: Begin with Boost Strength 0.25 in multiplicative mode, or Boost Strength 0.6 with Percentile Target 75 in additive mode. Adjust based on what you see in preview.
  • Preview before publishing: Use the sort order preview to verify that the right products are being boosted and that the lift looks reasonable. Each matched product shows a +N% badge with its computed lift.
  • Avoid over-boosting: Keep Boost Strength below 1.0 for most use cases to maintain natural ranking. In additive mode, values above 1 cause matches to overshoot the target.
  • Layer additive boosts intentionally: When stacking multiple additive boosts on the same metric, lifts add together. Use lower per-boost strength (0.3–0.5) when several boosts can match the same product.
  • Use additive mode for zero values: When boosting products with no performance data, always use additive mode — multiplicative mode cannot move products with a base score of zero.
  • Retune migrated additive rules: Additive sort orders created before 2026-05-02 use the legacy row-position formula. After the rewrite, open each one, preview it, and adjust Boost Strength and Percentile Target to match your intent.

​
See also