Skip to main content

​
Before you start

  • You can create multiple rules for the same collection + sort order combination using contextual conditions.
  • Rules can’t target the “all” collection.

​
Steps

  1. Go to Merchandise and click Create.
  2. Pick the collection and the sort order you want to enhance.
  3. Add Pins to place specific products at the top.
  4. Add Expressions (optional) to group similar products (e.g., by brand or type).
  5. Configure Options (optional):
    • Group Related Products Sequentially - Enable to display related products next to each other (requires sequences enabled on the sort order).
    • Disable Variant Breakouts - Enable to prevent variant breakouts from being applied when this rule is active (only shown if the collection has variant breakouts configured).
  6. Configure Scheduling (optional) to automatically enable/disable the rule based on time windows.
  7. Add Contextual Conditions (optional) to target specific audiences based on location, customer data, or UTM parameters.
  8. Save, then Publish when you’re ready.

​
Expression Operators

When building expressions, you can use various operators depending on the attribute type: Text operators:
  • equals / does not equal - Exact match
  • 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 (enables multi-select)
  • is null / is not null - Check if attribute has a value (hides value field)
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 (enables multi-select)
  • is null / is not null - Check if attribute has a value (hides value field)
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 (hides value field)
Tag operators:
  • contains / does not contain - Check if tag exists
  • in / not in - Match any tag in a list (enables multi-select)

​
Using Null Operators

The is null and is not null operators check whether an attribute has been set. When you select these operators, the value field is automatically hidden since no comparison value is needed. Example use cases:
  • vendor is not null - Only show products with a vendor assigned
  • compare_at_price is null - Show products not on sale
  • tags is null - Show untagged products

​
Using Multi-Select Operators

When you select in or not in operators, the UI automatically enables multi-select, allowing you to match products against multiple values in a single expression. Example:
  • vendor in [Nike, Adidas, Puma] - Show products from any of these brands
  • tags in [featured, bestseller, new-arrival] - Show products with any of these tags

​
Scheduling

Set a start date and time to automatically enable the rule at a specific moment. Optionally set an end date and time to automatically disable it. A background job runs every minute to evaluate schedules and update rule status. Use cases:
  • Flash sales that start and end at specific times
  • Seasonal campaigns scheduled weeks in advance
  • Product launch merchandising that goes live at release time

​
Contextual Conditions

Define conditions based on visitor context to control when the rule applies. The system evaluates conditions using JSON Logic against session data including:
  • Geographic data (country, state, city)
  • Customer attributes (tags, account status)
  • UTM parameters (source, medium, campaign)
  • Device information (device type, OS)
Use cases:
  • Show different merchandising to US vs. UK visitors
  • Target mobile users with mobile-optimized product ordering
  • Display campaign-specific merchandising for visitors from specific marketing channels

​
Multiple Rules for the Same Collection

When you create multiple rules for the same collection/sort combination, the system uses first-match-wins evaluation. Rules are evaluated in creation order, and the first rule whose contextual conditions match is applied. Example: 
Rule 1: US visitors → US-specific merchandising
Rule 2: UK visitors → UK-specific merchandising
Rule 3: No conditions → Default merchandising
Create rules in priority order. Rules without contextual conditions always match and should be created last as fallback rules.

​
Overlap Detection

The system validates that contextual conditions don’t overlap to prevent multiple rules from matching the same visitor. When creating or updating a rule, the system checks if the conditions could match the same visitor as an existing rule. Allowed (non-overlapping):
  • country == US and country == CA
  • source == klaviyo and source == google
  • country in [US, CA] and country in [UK, DE]
Blocked (overlapping):
  • country == US and country == US
  • country in [US, CA] and country in [CA, UK]
  • country == US and country in [US, CA]
If your conditions overlap with an existing rule, you’ll see an error message identifying the conflicting rule by name. Update your conditions to be mutually exclusive or edit the existing rule.

​
Disable Variant Breakouts

If your collection has variant breakouts configured, you’ll see a Disable Variant Breakouts toggle in the Options tab. When enabled, this prevents variant breakouts from being applied to the collection while this rule is active. When to use this:
  • You want to show products as single tiles during a promotional campaign for cleaner presentation
  • You’re targeting specific audiences who should see products instead of individual variants
  • You want to temporarily disable variant breakouts during scheduled events without changing your global configuration
The option only appears when the target collection has variant breakouts configured. See Variant Breakouts for more information.

​
Tips

  • Use Pins for must-see items; use Expressions to organize the rest.
  • Combine scheduling with contextual conditions for powerful targeting (e.g., Black Friday rule only for US visitors).
  • Create a fallback rule without conditions to ensure all visitors see merchandising.
  • Use the Disable Variant Breakouts option to temporarily override variant breakout behavior for specific campaigns or contexts.