Merchandising Rules

Overview

The Merchandising Rules feature allows you to take control of how products are displayed on your collection pages. Unlike traditional sorting methods, merchandising rules give you the flexibility to:

Manually pin specific products to the top of a collection page
Create expressions that automatically group and prioritize products based on attributes
Combine both approaches in a hybrid strategy for maximum control
Use contextual conditions to target different audiences with different merchandising strategies
Schedule rules to automatically enable and disable based on time windows

Merchandising Architecture

The platform hierarchy determines the order in which products are displayed on collection pages. Dynamic Linking takes the highest priority, followed by Merchandising Rules, and finally the base Sort Order: Priority Hierarchy:

Dynamic Linking (first page only) - Products specified via the Browse API’s dynamicLinking parameter appear first
Merchandising Rules - Manually pinned products and expression-based groups
Base Sort Order - The underlying sort order for all remaining products

Dynamic Linking is applied via the Browse API and takes priority over all merchandising rules and sort orders. It only applies on the first page of results. Merchandising rules extend your Sort Orders rather than replace them. Products that aren’t dynamically linked, manually pinned, or matched by expressions will follow the base sort order you’ve selected.

Why Merchandising Matters

Use merchandising to spotlight key products, reflect campaigns, and shape the shopping journey. Rules let you combine manual pins with automated groupings so your strategy shows up consistently on collection pages—without losing the benefits of your base sort order. For step‑by‑step instructions, see:

Types of Merchandising

Layers offers three approaches to merchandising your collection pages:

Manual Merchandising

Manually pin specific products to appear at the top of your collection page, giving you precise control over which items receive the most visibility.

Automated Merchandising

Use expressions to automatically group and prioritize products based on attributes like product type, vendor, tags, or other criteria.

Hybrid Approach

Combine manual pinning with expressions for a comprehensive merchandising strategy that balances precision with automation.

Multiple Rules per Collection

You can create multiple merchandising rules targeting the same collection and sort order combination. This enables sophisticated merchandising strategies where different rules apply based on contextual conditions or time windows.

First-Match-Wins Evaluation

When multiple rules target the same collection/sort combination, the system evaluates them in database order (typically by creation date). The first rule whose contextual conditions match the current session context is applied. Rules without contextual conditions always match and act as fallback rules. Example scenario:

Rule 1: US visitors → Show US-specific merchandising
Rule 2: UK visitors → Show UK-specific merchandising  
Rule 3: No conditions → Default merchandising for all other visitors

When a visitor from the US browses the collection, Rule 1 matches first and is applied. UK visitors see Rule 2, and all other visitors see Rule 3.

Rules are evaluated in the order they were created. If you need to change rule precedence, you may need to recreate rules in the desired order.

Overlap Detection Validation

To prevent conflicting merchandising rules, the system validates that contextual conditions don’t overlap when creating or updating rules. This ensures that only one rule can match a given visitor at any time. What constitutes overlapping conditions: The system analyzes the contextual conditions of all existing rules for the same collection/sort combination and determines if the new rule’s conditions could match the same visitor as an existing rule. Non-overlapping conditions (allowed):

country == US and country == CA (different equality values)
country in [US, CA] and country in [UK, DE] (no common values)
source == klaviyo and source == google (different marketing sources)

Overlapping conditions (blocked):

country == US and country == US (identical conditions)
country in [US, CA] and country in [CA, UK] (common value: CA)
country == US and country in [US, CA] (US is in the list)

Validation behavior: When you attempt to create or update a rule with overlapping conditions, you’ll see an error message:

The contextual conditions overlap with an existing rule "[Rule Name]" 
for this collection and sort order.

This validation ensures your merchandising strategy remains predictable and prevents ambiguous situations where multiple rules could apply to the same visitor.

The overlap detection uses heuristic analysis and may not catch all complex overlapping scenarios with deeply nested OR conditions. The validation provides best-effort protection while allowing legitimate non-overlapping rules to coexist.

Contextual Conditions

Contextual conditions allow you to control when a merchandising rule applies based on visitor session data. Using JSON Logic expressions, you can target specific audiences with tailored merchandising strategies.

How Contextual Conditions Work

Contextual conditions are evaluated at request time against session context data including:

Geographic data: Country, state/province, city
Customer attributes: Customer tags, account status, purchase history
UTM parameters: Marketing source, medium, campaign
Device information: Device type, operating system
Shopping channel: Online store, mobile app, etc.

The system uses JSON Logic to evaluate conditions. If a rule’s conditions evaluate to true for the current session, that rule is applied. Rules without contextual conditions always match.

JSON Logic Examples

Target US visitors:

{
  "==": [
    {"var": "geo.country"},
    "US"
  ]
}

Target mobile users in California:

{
  "and": [
    {"==": [{"var": "geo.state"}, "CA"]},
    {"==": [{"var": "device"}, "mobile"]}
  ]
}

Target visitors from specific marketing campaigns:

{
  "in": [
    {"var": "marketing_campaign"},
    ["summer-sale", "holiday-promo"]
  ]
}

The contextual conditions form in the dashboard provides a user-friendly interface for building these JSON Logic expressions without writing code directly.

Use Cases for Contextual Conditions

Geographic Merchandising: Show region-specific products or promotions based on visitor location. Campaign-Specific Merchandising: Display different product arrangements for visitors arriving from specific marketing campaigns. Device-Optimized Merchandising: Adjust product ordering based on device type for optimal mobile or desktop experiences. Customer Segment Targeting: Show VIP customers different merchandising than first-time visitors.

Rule Scheduling

Rule scheduling allows you to automatically enable and disable merchandising rules based on time windows. This eliminates manual intervention for time-based promotions and seasonal merchandising.

How Scheduling Works

When you configure a schedule for a rule, you set:

Start date and time: When the rule should automatically enable
End date and time (optional): When the rule should automatically disable

A background job runs every minute to evaluate all scheduled rules and update their enabled status based on the current time. Scheduling behavior:

Rules with a start time in the past and no end time (or end time in the future) are automatically enabled
Rules with an end time in the past are automatically disabled
Rules with a start time in the future remain disabled until that time arrives
If no end time is specified, the rule remains enabled indefinitely after the start time

Scheduled rules work independently of contextual conditions. A rule must pass both its schedule check and contextual conditions (if any) to be applied.

Use Cases for Scheduling

Flash Sales: Schedule a rule to enable at the start of a flash sale and disable when it ends. Seasonal Campaigns: Set up holiday merchandising weeks in advance that automatically activates on the campaign start date. Product Launches: Schedule merchandising for new product releases to go live at a specific time. Time-Zone Specific Promotions: Combine scheduling with geographic conditions to run promotions at specific times in different regions.

Combining Scheduling with Contextual Conditions

You can use both scheduling and contextual conditions on the same rule for powerful targeting: Example: A Black Friday rule that only applies to US visitors and automatically enables on Black Friday morning and disables on Monday morning.

Schedule: 2024-11-29 00:00:00 to 2024-12-02 00:00:00
Contextual Condition: geo.country == "US"

This rule will only be active during the Black Friday weekend AND only for US visitors.

Conditional Pins

Conditional pins extend manual merchandising by allowing you to control when a pinned product should be active. Instead of pins being permanently visible, you can configure conditions that determine when each pin appears in your collection.

Condition Types

Always Pinned is the default behavior where the product stays pinned at its assigned position indefinitely. Use this for evergreen products that should always appear prominently. Scheduled Pins allow you to set a specific time window during which the pin is active. Configure a start date and time, and optionally an end date and time. The pin automatically activates when the schedule begins and deactivates when it ends. This is ideal for promotional periods, seasonal campaigns, or limited-time features. Advanced Conditions give you full control using custom rules based on product attributes. The pin is only active when the conditions evaluate to true for the pinned product. For example, you can configure a pin to only be active while the product is in stock, or while a specific variant is available.

How Conditional Pins Work

When you configure a conditional pin, the system continuously evaluates the conditions: For scheduled pins, a background process checks the current time against your configured schedule and automatically enables or disables the pin as needed. You don’t need to manually manage pins for time-based promotions. For advanced conditions, the system evaluates the rules against the current product data whenever the product is updated. If a product goes out of stock and your condition requires availability, the pin is automatically disabled until the product becomes available again.

Disabled conditional pins are visually indicated in the merchandising interface so you can see which pins are currently inactive and why.

Use Cases for Conditional Pins

Promotional Campaigns: Schedule pins for Black Friday, holiday sales, or flash promotions without manual intervention. Inventory-Aware Merchandising: Only pin products while they’re in stock, automatically removing out-of-stock items from prominent positions. Seasonal Rotations: Set up pins for seasonal collections that automatically activate and deactivate based on dates. Attribute-Based Visibility: Pin products only when they meet specific criteria, such as having a certain tag or being from a particular vendor.

Understanding Merchandising Expressions

Expressions are powerful rules that automatically sort products based on attributes like product type, vendor, price, or any other filterable attribute in your catalog.

Expressions are applied after manual/conditional pins and before the primary sort order. This means pinned products always appear first, followed by products matching expressions, and finally all remaining products sorted by the base sort order.

How Expressions Work

Dynamic Linking products appear first (if applied via Browse API on page 1)
Manually pinned products appear next
Products matching your expressions appear in the order of the expressions
Within each expression group, products are sub-sorted by your selected base sort order
Products not matching any expression follow at the end, sorted by the base sort order

Available Operators

When building expressions, you can use various operators depending on the attribute type: Text operators:

equals / does not equal - Exact match comparison
contains / does not contain - Partial text matching
begins with / does not begin with - Prefix matching
ends with / does not end with - Suffix matching
in / not in - Match any value in a list (multi-select enabled in UI)
is null / is not null - Check if attribute has a value (no value field shown in UI)

Numeric operators:

equals / does not equal - Exact numeric match
greater than / greater than or equal - Value comparisons
less than / less than or equal - Value comparisons
between / not between - Range matching (requires two values)
in / not in - Match any value in a list (multi-select enabled in UI)
is null / is not null - Check if attribute has a value (no value field shown in UI)

Date operators:

equals / does not equal - Exact date match
after / before - Date comparisons
between / not between - Date range matching (requires two values)
is null / is not null - Check if attribute has a value (no value field shown in UI)

Tag operators:

contains / does not contain - Check if tag exists
in / not in - Match any tag in a list (multi-select enabled in UI)

When you select is null or is not null operators, the value field is automatically hidden in the UI since these operators check for the presence or absence of data without requiring a comparison value.

When to Use Null Operators

The is null and is not null operators are useful for filtering products based on whether an attribute has been set: Example use cases:

vendor is not null - Only show products that have a vendor assigned
compare_at_price is null - Show products that are not on sale (no compare-at price set)
metafield.custom.featured_until is not null - Show products with a featured end date configured
tags is null - Show untagged products that need categorization

Example Use Case

Let’s say you want to group products in your “New Shoes” collection by product type, while using the “Best-selling” sort order:

Expressions:
product_type = Sneakers
product_type = Sandals
product_type = Boots

Result:

All Sneakers appear first, sub-sorted by best-selling rank
Then all Sandals, sub-sorted by best-selling rank
Then all Boots, sub-sorted by best-selling rank
Finally, any remaining shoes (like Slippers or Loafers) sorted by best-selling rank

Expressions at a Glance

Expressions automatically group products (for example by type, brand, or price range) so you can present curated blocks that still respect your selected base sort within each group. Use them alongside pinned products for a balanced strategy.

Soft Boost Expressions

In addition to standard priority rule expressions that push matching products to the top of a collection, merchandising rules support soft boost expressions. Soft boosts apply a decaying multiplier to gently blend matching products higher in the sort order, creating natural interleaving rather than hard grouping.

Soft boost in merchandising works the same way as Soft Boost in Sort Orders, but is scoped to a specific merchandising rule instead of applying globally. This lets you boost products contextually — for example, boosting “sale” items only for visitors from a specific campaign.

How Soft Boost Expressions Work

When you create an expression in the merchandising rule builder, you can choose between two expression types:

Priority Rule (default): Pushes all matching products to the top of the sort order as a group.
Soft Boost: Applies a decaying boost that naturally interleaves matching products throughout the results based on their existing sort performance.

Soft boost expressions are visually distinguished in the rule builder with an amber badge and sparkle icon, making them easy to identify alongside standard expressions.

Boost Modes

Soft boost expressions support two modes: Multiplicative (default) amplifies products that already perform well on the base sort metric. The existing sort value is scaled by a boost factor, so products with higher base values receive a proportionally stronger lift. Best for promoting products that are already performing and have non-zero metric values. Additive (percentile-based) assigns a fixed position based on a configurable percentile target, boosting products even when they have zero or near-zero base values. Best for sprinkling in products that may not have metric data yet — like new arrivals, recently restocked items, or products in a new category.

Configuration Parameters

Parameter	Mode	Description
Boost Strength	Multiplicative	Controls how much the base metric value is amplified (0–2). Higher values push matching products further up relative to their existing performance. Default: 0.25.
Percentile Target	Additive	Where matching products land in the sort order (0–100%). At 100% they appear near the top; at 50% they blend into the middle. Default: 50%.
Decay Rate	Both	Controls how quickly the boost fades across ranked products (1–500). Lower values concentrate the lift on top matches; higher values spread it more evenly. Default: 100.

When to Use Soft Boost vs. Priority Rules

Scenario	Recommended Type
Feature a seasonal tag across the entire collection	Priority Rule
Gently promote new arrivals without displacing best sellers	Soft Boost (Additive)
Amplify high-performing sale items during a campaign	Soft Boost (Multiplicative)
Group products by category or brand at the top	Priority Rule
Sprinkle restocked items throughout a best-selling sort	Soft Boost (Additive)

Soft boost expressions support the same targeting conditions as priority rule expressions. You can combine contextual conditions (geo, device, customer segment) with soft boosts for precise audience targeting.

Sell-Out Pin Deletion

Merchandising rules can automatically remove pinned products when they sell out, keeping your collection pages fresh without manual intervention. This feature operates at two levels: per-rule and store-wide with location filtering.

Per-Rule Sell-Out Deletion

Each merchandising rule has a Delete Pins on Sell Out toggle. When enabled, any pinned product in that rule is automatically removed if it becomes unavailable (sold out globally). This is evaluated whenever a product’s inventory is updated. How it works:

When a product’s inventory reaches zero and it is no longer available for sale, its pin is deleted from the rule
The pin count for the rule is updated automatically
The rule’s cache is flushed so the change takes effect immediately on the storefront
If the product comes back in stock, you would need to re-pin it manually

If the store-level Auto-delete rule pins on product removal setting is enabled, pins are deleted on sell-out for all rules regardless of each rule’s individual toggle.

Location-Based Inventory Filtering

For merchants with multiple fulfillment locations, the platform supports location-based sell-out checks. Instead of relying on global inventory, you can specify which Shopify locations should be considered when determining if a product is “sold out” for pin deletion purposes. This is configured in the dashboard under Settings → Search Behavior → Sell Out Check Locations. How location filtering works:

Select one or more Shopify locations from the multi-select picker
A product is considered “sold out” only when it has zero inventory at all selected locations
Products that are not tracked at any of the selected locations are not treated as sold out (no false positives)
The check runs both during bulk inventory evaluation and when individual products are updated
Leave the location selection empty to use global inventory (default behavior)

Use cases:

Regional fulfillment: Only unpin products when they sell out at your primary warehouse, even if stock remains at a secondary location
Retail vs. online: Track sell-out based on your online fulfillment center, ignoring retail store inventory
Multi-warehouse operations: Consider a product sold out only when all key warehouses are empty

Location-based sell-out filtering applies store-wide to all rules that have Delete Pins on Sell Out enabled (or when the store-level auto-delete setting is active). You cannot configure different location filters per rule.

Disabling Variant Breakouts

Merchandising rules include an option to disable variant breakouts for a collection when the rule is active. This allows you to override the default variant breakout behavior configured for a collection. When you enable the Disable Variant Breakouts option on a merchandising rule:

Variant breakouts will not be applied to the collection while this rule is active
Products will display as standard product tiles instead of individual variant tiles
This override only applies when this specific rule is the active rule for the collection

This is useful when you want to temporarily disable variant breakouts for specific merchandising campaigns or contexts without modifying your global variant breakout configuration. Use cases:

Promotional campaigns where you want to show products as single tiles for cleaner presentation
Contextual merchandising where certain audiences should see products instead of variants
Scheduled events where variant breakouts should be disabled during specific time windows

The Disable Variant Breakouts option only appears in the merchandising rule form when the target collection has variant breakouts configured. If no variant breakouts exist for the collection, this option is not shown.

See Variant Breakouts for more information on how variant breakouts work and how merchandising rules can override them.

Tips for Effective Merchandising

Align with Marketing Campaigns: Coordinate your merchandising efforts with ongoing marketing campaigns for a unified promotional strategy.
Seasonal Adjustments: Update your merchandising to reflect seasonal trends, holidays, or shopping events.
Customer Insights: Use customer behavior data to inform your merchandising decisions, ensuring that the most relevant products are highlighted.
Balance Manual and Automated Approaches: Use manual pinning for your most important products, and expressions for broader category organization.
Test Different Strategies: Experiment with different expression combinations to find what works best for your store.

Example Scenarios

Holiday Season: During the holiday season, pin gift sets at the top, then use expressions to group products by price range (under $25,$ 25- $50, over$ 50).
New Collection Launch: Pin featured items at the top, then use expressions to group remaining products by collection theme or color.
Sales Promotions: Pin highest-discount items at the top, then use expressions to group products by discount percentage ranges.
Category Organization: Use expressions to group products by sub-category, brand, or material while maintaining your best-selling sort order within each group.

By following this guide and utilizing the full suite of merchandising tools available on our platform, you’ll be able to merchandise category pages that not only look great but also drive conversions and enhance the customer shopping experience.

Overview

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Misc

Legal

​Overview

​Merchandising Architecture

​Why Merchandising Matters

​Types of Merchandising

Manual Merchandising

Automated Merchandising

Hybrid Approach

​Multiple Rules per Collection

​First-Match-Wins Evaluation

​Overlap Detection Validation

​Contextual Conditions

​How Contextual Conditions Work

​JSON Logic Examples

​Use Cases for Contextual Conditions

​Rule Scheduling

​How Scheduling Works

​Use Cases for Scheduling

​Combining Scheduling with Contextual Conditions

​Conditional Pins

​Condition Types

​How Conditional Pins Work

​Use Cases for Conditional Pins

​Understanding Merchandising Expressions

​How Expressions Work

​Available Operators

​When to Use Null Operators

​Example Use Case

​Expressions at a Glance

​Soft Boost Expressions

​How Soft Boost Expressions Work

​Boost Modes

​Configuration Parameters

​When to Use Soft Boost vs. Priority Rules

​Sell-Out Pin Deletion

​Per-Rule Sell-Out Deletion

​Location-Based Inventory Filtering

​Disabling Variant Breakouts

​Tips for Effective Merchandising

​Example Scenarios

​See also

Overview

Merchandising Architecture

Why Merchandising Matters

Types of Merchandising

Multiple Rules per Collection

First-Match-Wins Evaluation

Overlap Detection Validation

Contextual Conditions

How Contextual Conditions Work

JSON Logic Examples

Use Cases for Contextual Conditions

Rule Scheduling

How Scheduling Works

Use Cases for Scheduling

Combining Scheduling with Contextual Conditions

Conditional Pins

Condition Types

How Conditional Pins Work

Use Cases for Conditional Pins

Understanding Merchandising Expressions

How Expressions Work

Available Operators

When to Use Null Operators

Example Use Case

Expressions at a Glance

Soft Boost Expressions

How Soft Boost Expressions Work

Boost Modes

Configuration Parameters

When to Use Soft Boost vs. Priority Rules

Sell-Out Pin Deletion

Per-Rule Sell-Out Deletion

Location-Based Inventory Filtering

Disabling Variant Breakouts

Tips for Effective Merchandising

Example Scenarios

See also