Skip to main content

​
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:
  1. Manually pin specific products to the top of a collection page
  2. Create expressions that automatically group and prioritize products based on attributes
  3. Combine both approaches in a hybrid strategy for maximum control
  4. Use contextual conditions to target different audiences with different merchandising strategies
  5. 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:
  1. Dynamic Linking (first page only) - Products specified via the Browse API’s dynamicLinking parameter appear first
  2. Merchandising Rules - Manually pinned products and expression-based groups
  3. 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

  1. Dynamic Linking products appear first (if applied via Browse API on page 1)
  2. Manually pinned products appear next
  3. Products matching your expressions appear in the order of the expressions
  4. Within each expression group, products are sub-sorted by your selected base sort order
  5. 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:
1. product_type = Sneakers
2. product_type = Sandals
3. 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
Merchandising Expressions Example

​
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.

​
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, 25-50,over50, 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.

​
See also