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.
- Date and time: Current date, time, and day of the week in your store’s timezone
- Shopper activity: Products the shopper viewed, has in their cart, or purchased
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 seven groups:
Each group opens its own menu, with related fields listed under section headings (for example, Profile and Order history under Customer). Type in the search box to find a field across every group. Integration fields show the provider’s logo and only appear after you connect that integration. 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 Klaviyo Campaign field in the Traffic 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 members of a Shopify customer segment:
The Segments field in the Customer group targets shoppers who belong to a Shopify customer segment. Selecting the field opens a picker listing every segment defined in your Shopify admin. Search by name and select one or more segments. This field supports the “is in list” and “is not in list” operators.
Layers syncs your Shopify segments in the background and keeps them up to date as shoppers join or leave. Membership is resolved server-side from the signed-in customer, so guests never match. Newly created segments become targetable once Layers has finished the initial member sync. Large segments may take a few minutes to become available in the picker. Segments are matched by their Shopify segment ID, so renaming a segment in Shopify keeps existing rules working.
Target visitors in a specific Shopify Market (by handle):
Target visitors in markets that include a specific country:
The Market Countries field in the Geography 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.
Date and time conditions
The Date & time group lets you apply a rule, sort order expression, soft boost, or block rule only at certain dates and times. Use it for recurring or time-boxed windows, such as boosting clearance items over a holiday weekend or brunch items on weekend mornings.
The greater than and less than operators also have “or equal” variants. The between operator includes both bounds.
Boost clearance items over Black Friday weekend:
Boost brunch items on weekend mornings (combine with AND):
Boost late-night snacks overnight:
How date and time conditions are evaluated:
- Layers evaluates every Date & time field in your store’s timezone, synced from your Shopify store settings. Until the first sync completes, Layers uses UTC. The field description in the picker shows which timezone applies.
- The dates and times you enter have no timezone of their own. Layers compares them against the current local time in your store’s timezone.
- Enter Current Time values as two-digit hours and minutes, such as
09:30. Layers rejects values like9:30when you save the condition. - A Current Time window can wrap past midnight. Enter the later time first to create an overnight window. For example, between 22:00 and 06:00 matches from 22:00 through 06:00 the next morning. Not between with the same values matches every other time.
- Date and time conditions don’t depend on shopper context. A sort order expression that uses a Date & time field still applies to requests that send no
context. In an OR group, the date and time condition can match on its own even when the other conditions have no data to match. - Layers caches results briefly, so a condition can take a short time to switch on or off after a schedule boundary passes.
Date and time conditions differ from rule scheduling. Rule scheduling publishes or unpublishes an entire merchandising rule once. Date and time conditions work anywhere contextual conditions are supported and can repeat, such as every weekend.
Shopper activity conditions
The Shopper activity group targets shoppers based on the products in their session. Use it to show accessories to shoppers who viewed a camera, or to hide a product the shopper already bought.
These fields read the
productsViewed, productsInCart, and productsPurchased arrays in the contextual payload.
Select an operator, then select Choose products… to open the product sheet:
- include: the condition matches when enough of the shopper’s products match your product rules.
- do not include: the condition matches when none of the shopper’s products match your product rules.
- strongly prefers: available on the Strongly prefers field. The condition matches when the products you select dominate the shopper’s recent activity. Layers merges the shopper’s views, cart adds, and purchases over the last 90 days into one stream, weights purchases above cart adds above views, and decays older events. The condition matches when matching products make up most of that weighted activity, so a shopper who keeps coming back to boots is targeted even if they occasionally look at sandals. There are no count or time-window controls; you only pick the product rules.
- Count: select at least, at most, or exactly, then enter a number. The default is at least 1. The sheet hides the count for do not include.
- Time window (Products Viewed and Products Purchased only): select any time, the last 24 hours, the last 7 days, or the last 30 days.
- Product rules: build rules on product fields such as product type, vendor, tags, or price. Only product fields are available here.
Target shoppers who bought exactly one gift card:
Preview matching products
While you edit product rules, the sheet previews which catalog products match them. It shows the number of matches and up to 12 product thumbnails. On large catalogs, Layers only checks part of the catalog, and the preview says how many products it checked. The preview can’t evaluate rules on shopper-specific fields, such as the selected variant, options, or the viewed or purchased time. Select Apply and test the condition against real traffic instead.
How time windows are evaluated:
- A time window only counts products whose view or purchase timestamp falls inside the window. Products sent without a timestamp don’t count toward a windowed condition.
- Layers reads the timestamp from the
atfield on eachproductsViewedandproductsPurchasedentry, in Unix milliseconds. If you send context yourself, includeaton every entry you want a windowed condition to count.
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. - Every discovered parameter appears in the Custom group of the field picker, including parameters grouped under a namespace (for example, a points balance sent under a Yotpo namespace). Search matches the parameter key, so you can type
yotpoto find it. - 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.