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
- Click source: The ad network or email/SMS platform derived from landing URL click identifiers
- Device information: Device type, operating system
- Shopping channel: Online store, mobile app, etc.
Condition examples
The contextual conditions form in the dashboard lets you build these targeting rules without writing code. Selecting a field opens a picker that organizes fields into groups: Channel, Campaign, Customer, Location, Markets, B2B, one group per connected integration (for example, Klaviyo or Listrak), and a Custom group for custom context parameters your storefront sends. Below are common examples of what you can set up. Target US visitors:
Target mobile users in California (combine with AND):
Target visitors from specific marketing campaigns:
Target visitors from a specific Klaviyo campaign:
The Campaign field in the Klaviyo group is available once you connect Klaviyo under Settings → Integrations. Select a campaign from the dropdown and Layers matches shoppers whose session UTMs came from that campaign across email, SMS, and push. See Klaviyo for setup details.
Layers normalizes the campaign’s UTM tags and the shopper session before comparing them. Casing, surrounding whitespace, and common aliases resolve to the same value. For
utm_source, fb, ig, x, goog, and yt map to facebook, instagram, twitter, google, and youtube. For utm_medium, paid and ppc map to cpc, seo maps to organic, ref maps to referral, banner maps to display, and aff maps to affiliate. A campaign tagged utm_medium=Paid still matches a session whose medium arrives as cpc.
Target visitors who arrived from a Meta link click:
The Click Source field targets shoppers whose landing URL carried a network’s click identifier (for example,
fbclid or gclid), whether or not the link was tagged with UTMs. It covers the major ad networks plus email and SMS platforms that tag their own links (Klaviyo, Listrak). A click from a network is not proof of a paid ad. Meta, for example, appends its click identifier to organic link clicks too. See Click identifiers for the full list of supported networks.
Target customers with specific tags:
You can target shoppers based on Shopify customer tags (for example, “vip”, “wholesale”, or any tag synced from Shopify). Use “is in list” or “is not in list” to match against multiple tags, or “contains” to match any tag that includes a substring.
Target visitors in a specific Shopify Market (by handle):
Target visitors in markets that include a specific country:
The Country (in regions) field in the Markets group targets countries included in the shopper’s Shopify Market region. Selecting the field opens a searchable dropdown listing every country in your store’s active Shopify Markets. Search by country code, country name, or market name. You can still type a custom two-letter country code if it isn’t listed. This field supports the “is in list” and “is not in list” operators.
Custom context fields
Layers automatically discovers the custom context parameters your storefront sends with each request and offers them as condition fields. You don’t register custom fields anywhere. Once a parameter appears in your store’s traffic, it shows up in the field picker. For example, if your storefront sends a subscription status (such as “active” or “paused”) with each request, you can target it once it’s discovered:
How discovery works:
- Layers scans the last 7 days of storefront traffic once a day for custom parameters. A newly sent parameter becomes targetable after the next daily scan, not immediately.
- Discovery covers all storefront traffic: tracking events from the Storefront Pixel and the
contextparameter on Search, Browse, and Blocks API requests. Headless integrations that only send context through API requests get discovery too. - Top-level parameters appear in the Custom group of the field picker. Parameters grouped under a namespace (for example, a points balance sent under a Yotpo namespace) appear in a group named after that namespace, alongside any fields Layers already ships for that integration.
- The value editor matches the type of the values your storefront actually sends: text, number, or a boolean checkbox.
- Because a field only appears after Layers has seen it in traffic, every offered field has real recorded values behind its picker.
- Parameter keys must contain only letters, numbers, underscores, and hyphens, and be at most 64 characters. Layers skips other keys.
- Values must be text, numbers, or true/false, either at the top level or nested one namespace deep. Layers doesn’t discover deeper nesting.
- Layers skips rarely sent parameters as noise. A parameter needs at least 5 occurrences in the 7-day window.
- Layers treats parameters with more than 500 distinct values as identifiers (cart tokens, per-shopper hashes) and skips them, since they can’t produce a usable value picker.
- Each store gets up to 40 discovered fields. Layers keeps the most frequently sent parameters.
- If a discovered parameter shares a name with a field Layers already ships (for example, an integration field like Klaviyo › Campaign), the shipped field wins.
Case sensitivity
String-based condition operators are case-insensitive. A condition matching “klaviyo” also matches “Klaviyo” or “KLAVIYO”. This coversequals, does not equal, in, not in, contains, does not contain, begins with, does not begin with, ends with, and does not end with whenever the value is a string. Numeric and boolean equality stays exact.
Case-insensitive matching applies wherever contextual conditions are evaluated, including merchandising rules, request transforms, sort orders, and block rules.