Merchandising Rules
The recommendation engine ranks products automatically using your store's order and browsing data. Merchandising rules let you override those rankings by hand: without touching the algorithm, rebuilding the output, or writing code. You can push a product to the top, bury a clearance item, force a specific product into a fixed slot, or prevent a product from ever appearing.
Rules take effect at the moment a recommendation is served. Publish a change, and the next shopper to request that placement gets the updated results.
Where to find them
Go to Commerce → Recommendations in the side navigation, open a recipe's detail page, and scroll to the Merchandising rules section. This is where you add, edit, enable, disable, and delete rules for that recipe.
- The Add rule button opens the rule form.
- Each existing rule shows its kind, its match criteria, and its scope.
- The enabled toggle on each rule.
Creating a rule
- Click Add rule.
- Pick a Rule type: Boost, Bury, Pin, or Exclude.
- Under Match items by, choose SKUs, Category, or a product attribute, and fill in the value.
- For a boost or bury, set the weight. For a pin, set the slot (0-based).
- Choose the rule's scope: this recipe only, or all recipes in the project.
- Click Preview impact to see the Added, Removed, and Moved products before you commit.
- Click Add rule to save it.
You know it worked when the new rule appears in the list above the form, with the kind, match criteria, and scope you set. If the button stays disabled, a required field is missing: every rule needs at least one match condition, and boost, bury, and pin each need their own extra field filled in.
The four rule kinds
Boost: promote a product
A boost rule raises a product's position in the results by multiplying its score by a number greater than 1, up to 1000. A multiplier of 2 roughly doubles the product's score; a multiplier of 5 pushes it much higher.
Use boosts when you want to favour a product without guaranteeing its position: for example, promoting a hero product during a campaign while still letting the algorithm order everything else.
Bury: demote a product
A bury rule lowers a product by multiplying its score by a number between 0 and 1 (not zero itself). A multiplier of 0.5 halves the score; 0.1 pushes the product near the bottom.
Use buries for products you want to keep available but not lead with: for example, a slow-moving line you need to shift without actively excluding it.
Pin: fix a product to a slot
A pin rule forces a product into a specific position in the results, regardless of its ranking score. Position numbers start at 0 (the first item in the list) and go up to 100.
A pin only takes effect when the slot number is within the number of items you are displaying. If your placement shows 6 products and you pin to slot 8, the pinned product is trimmed off and nothing is shown in its place.
A product can only be pinned once. If you have two rules that would try to pin the same product, the first rule (lowest slot number) wins. Pins resolve in ascending slot order, so earlier pins settle before later ones.
When you pin by SKU, the engine can also inject a product: if the SKU you named is not already in the candidate pool, the engine fetches it from the Live Catalog and inserts it at the pinned slot. If the SKU is not in your Live Catalog, the pin is silently skipped, no broken card is ever shown. A product covered by an exclude rule is never injected.
Exclude: never show a product
An exclude rule removes a product from the results entirely, regardless of how well the algorithm ranked it. The excluded product is gone before any other rules run.
No pin can bring an excluded product back: not a category pin, not an attribute pin, and not a pin that names the exact SKU. Exclusions are applied first and nothing later in the chain undoes them. If you do end up with both rules on the same product, the rule list flags the pin as cancelled, so you can see which of the two is doing nothing.
Use exclusions for discontinued products, products with legal restrictions on display, or anything you never want surfacing in recommendations.
Matching: which products a rule applies to
Every rule needs to tell the engine which products it targets. You can match on one of the following, or combine them (all conditions must hold):
By specific SKUs
List one or more product SKUs. The rule applies only to products whose SKU is in the list.
This is the most precise match. Boost, bury, pin, and exclude all work reliably with SKU lists.
By category
Enter a category name. The rule applies to any product whose category field matches, or whose categories list contains that value. Category matching reads the category stored in the Live Catalog row for each product.
Category-based pins work on products already in the pool: they move the first matching product to the pinned slot but cannot inject a product from outside the pool.
By product attribute
Pick a field, an operator, and a value. The rule applies to products where the field satisfies the condition.
Fields can be standard product fields (title, availability, price, and so on) or custom fields you supplied in your catalog data.
| Operator | Meaning |
|---|---|
eq | Equals |
neq | Does not equal |
gt | Greater than |
gte | Greater than or equal to |
lt | Less than |
lte | Less than or equal to |
contains | Field (as text) contains the value |
in | Field value is one of a list |
A product whose field is missing or undefined does not match: the rule simply skips that product rather than throwing an error.
Combining conditions
If you set more than one condition on a rule (for example, a category plus an attribute), all of them must hold for the rule to match a product. This is an AND combination: there is no OR within a single rule. To apply a rule to products that meet either of two conditions, create two separate rules.
At least one condition is required. A rule with no match criteria is rejected.
Scope: one recipe or all recipes
When you create a rule, you choose whether it applies to:
- This recipe only: the rule affects only the recipe you are viewing.
- All recipes in this project: the rule applies across every recipe in the project, in addition to any recipe-specific rules those recipes have.
Use project-wide scope for rules that reflect business-wide decisions (always exclude a discontinued brand, always boost a seasonal hero). Use recipe-specific scope for rules that make sense only in one placement (pin a specific product first on the homepage carousel).
On the recipe's detail page, you can see both kinds side by side, each labelled with its scope.
Preview a rule's impact
Before you save a rule, use Preview impact in the rule form to see exactly what it changes. A vs B runs the recipe twice against the live serving path (once with your current rules, once with the new (or edited) rule added) and shows the difference:
- Added: products the rule brings into the list.
- Removed: products the rule takes out (an exclude, or a bury that pushes them past the trim).
- Moved: products whose rank changes, with their before and after positions.
For product‑based recipes (Similar, Bought together), pick an example product to preview against; list recipes (Bestsellers, Trending) preview against the whole catalog with no example needed. The preview is a dry run: nothing is saved and live shoppers are unaffected until you actually save the rule.
The preview compares the two served lists. It does not explain why an individual product ranks where it does: that per‑item scoring isn't surfaced yet.
When rules take effect
Rules go live on the next datafile publish. When you create, edit, or delete a rule, A vs B republishes the datafile immediately: so the new behaviour is live within the edge-cache window (about a minute) without waiting for the nightly ranking job.
The nightly ranking is not rerun when you change a rule. Merchandising applies to the most recent nightly output, so the ranking scores the algorithm computed are the starting point and your rules adjust from there.
When an exclude rule and a pin rule target the same product, the exclude wins. See Exclude: never show a product above.
Session affinity re-ranking
Each recipe has an optional Session affinity toggle. When it is on, the engine gently re-ranks results toward categories the current shopper is most engaged with: based on what they have recently viewed, have in their cart, or are currently looking at.
The adjustment happens at serve time using the seed context already sent with every recommendation request (the products the visitor viewed or currently has in cart). The engine looks up the category of each seed product from the Live Catalog and applies a mild score boost (a 1.5x multiplier) to any candidate whose category overlaps with those seeds. The ranking algorithm's relative ordering is otherwise preserved.
Session affinity is category-based. It does not use co-occurrence data or purchase history at serve time, only the categories of the products you pass as seeds.
The toggle is off for all existing recipes. Turn it on per recipe in the recipe's detail page. When off, no re-ranking happens.
To configure it: open a recipe's detail page and look for the Session affinity toggle near the recipe parameters.
How rules, affinity, and ranking work together
When a recommendation is served, the engine applies steps in this order:
- Exclude: any excluded products are removed from the candidate pool.
- Boost and bury: surviving products get their scores multiplied by any matching boost or bury rules. Multiple rules on the same product stack (the multipliers are combined).
- Session affinity: if the toggle is on, products whose category matches the shopper's recent activity get a further score boost.
- Re-rank: if any score was changed by steps 2 or 3, the pool is sorted by the adjusted scores. If no scores changed, the original ranking order is kept exactly as the algorithm produced it.
- Pin: pinned products are moved (or injected from the Live Catalog) into their fixed slots, in slot-number order. Anything removed by step 1 stays removed.
- Trim: the final list is cut to the number of items your placement requests.
Enabling and disabling rules
Each rule has an enabled toggle. A disabled rule has no effect on results: it stays saved so you can switch it back on without re-entering it. Use this to pause a seasonal promotion without deleting the rule.