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.

Contextual conditions allow you to control when a merchandising rule applies based on visitor session data. Using JSONLogic 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
  • Market data: Market ID, market handle, market countries
  • 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 JSONLogic 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 and act as default/catch-all rules. When multiple rules target the same collection, rules with contextual conditions are always evaluated before default rules. This ensures that a more specific conditional rule is never blocked by a default rule, regardless of creation order.

​
JSONLogic 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"]
  ]
}
Target visitors in a specific Shopify Market (by handle): 
{
  "==": [
    {"var": "market.handle"},
    "ca"
  ]
}
Target visitors in markets that include a specific country: 
{
  "in": [
    "US",
    {"var": "market.countries"}
  ]
}
The contextual conditions form in the dashboard provides a user-friendly interface for building these JSONLogic expressions without writing code directly.

​
Case sensitivity

String-based condition operators (contains, does not contain, begins with, does not begin with, ends with, does not end with) are case-insensitive. A condition matching “klaviyo” will also match “Klaviyo” or “KLAVIYO”. This applies wherever contextual conditions are evaluated, including merchandising rules, search rules, sort orders, and block rules.

​
Overlap detection

When you create or edit contextual conditions in the dashboard, Layers automatically checks whether your conditions overlap with another merchandising rule targeting the same collection and sort order. If an overlap is detected, a warning toast appears with the name of the conflicting rule and a link to view it. Two rules overlap when their conditions could match the same visitor session — for example, two rules that both target the same country or use a “contains” check that matches a subset of the other rule’s values. Overlap detection helps you avoid situations where a visitor could match multiple conditional rules unexpectedly. If you see an overlap warning, review both rules to confirm the intended priority or adjust the conditions to make them mutually exclusive.

​
Use cases

Geographic merchandising: Show region-specific products or promotions based on visitor location. Market-specific merchandising: Apply different product arrangements per Shopify Market, so shoppers in your EU market see a different collection grid than shoppers in your North America market. 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.

​
See also