Context data structure

The context parameter in search, browse, blocks, and facet requests accepts the following structured data. The snippets below show the value for a single context key, not a top-level request body. All fields must be nested inside the context object.

Geographic information

Location data used for regional merchandising and localized search results. For client-side requests, Layers automatically determines the customer’s location based on their IP address. For headless integrations making server-side API calls, you should pass geo information explicitly.

{
  "geo": {
    "country": "US",
    "province": "California",
    "city": "Los Angeles"
  }
}

Products in cart

Current cart contents help surface complementary products and influence relevance scoring.

{
  "productsInCart": [
    {
      "title": "Nike Air Force 1",
      "price": "110.00",
      "type": "Shoes",
      "productId": "1234567890",
      "variantId": "9876543210",
      "options": {
        "Size": "11",
        "Color": "White"
      }
    }
  ]
}

Fields:

title (string, optional): Product title
price (number, optional): Unit price in the request currency’s major units (e.g. 110.00 for $110), not cents. Accepts a JSON number or a numeric string such as "110.00".
type (string, optional): Product type
productId (string, optional): Shopify product ID. Accepts numeric or GID string form.
variantId (string, optional): Shopify variant ID
options (object, optional): Key-value pairs of variant options
quantity (integer, optional): Number of units of this line in the cart. Accepts a number or numeric string, such as 2, 2.0, or "2". Layers rounds fractional values down to a whole number. Missing values, non-numeric values, and values below 1 count as 1.

Behavior:

Each entry needs at least a productId, variantId, or non-empty title. Layers drops entries with none of these and records a developer notice.
If an optional field is malformed, such as a non-numeric price, Layers removes only that field and keeps the rest of the entry.
Cart-anchored blocks use every entry with a valid productId as an anchor product, not just the first. Layers removes duplicate products while preserving cart order. Entries without a productId aren’t used as block anchors.
Title-only entries still work in contextual conditions that match on product title.

Free shipping threshold

The cart subtotal at which the shopper qualifies for free shipping. Free Shipping Picks blocks use it with productsInCart prices and quantities to recommend products that close the gap.

{
  "freeShippingThreshold": 75
}

Fields:

freeShippingThreshold (number, optional): Threshold in the request currency’s major units (e.g. 75.00 for $75), not cents. Accepts a number or a numeric string, such as "75.00".

Behavior:

If the value is missing, non-numeric, or not greater than 0, Layers ignores it. The request still succeeds, and Layers keeps the rest of the context.
The app embed doesn’t send this field. Pass it yourself on requests for Free Shipping Picks blocks.

Purchase history

Previously purchased products inform recommendations and prevent over-promotion of already-owned items.

{
  "productsPurchased": [
    {
      "title": "Nike Air Force 1",
      "price": "100.00",
      "type": "Shoes",
      "productId": "1234567890",
      "variantId": "1111111111",
      "at": 1721390400000,
      "options": {
        "Size": "13",
        "Color": "Black"
      }
    }
  ]
}

Fields:

title (string, optional): Product title
price (number, optional): Unit price in the request currency’s major units (e.g. 110.00 for $110), not cents, at time of purchase. Accepts a JSON number or a numeric string such as "110.00".
type (string, optional): Product type
productId (string, optional): Shopify product ID
variantId (string, optional): Shopify variant ID
at (integer, optional): Timestamp of the purchase in Unix milliseconds. Required for Products Purchased conditions that use a time window and for the Replenish strategy.
options (object, optional): Key-value pairs of variant options

Like cart entries, each purchase entry needs at least a productId, variantId, or non-empty title.

Prior searches

Recent search queries and their outcomes help understand customer intent and refine relevance models.

{
  "priorSearches": [
    {
      "searchQuery": "running shoes",
      "hadClick": true,
      "hasResults": true
    }
  ]
}

Fields:

searchQuery (string, required): The search query text. Layers drops entries with a missing or empty query.
hadClick (boolean, optional): Whether the customer clicked on any results. Defaults to false when omitted, null, or not a boolean.
hasResults (boolean, optional): Whether the search returned any results. Defaults to false when omitted, null, or not a boolean.
fromPage (string, optional): The page the search was started from, such as the referring page URL or page type. Layers accepts this field but doesn’t currently use it for ranking or rules.

Marketing attribution

UTM parameters and marketing campaign information for attribution tracking.

{
  "marketing": {
    "source": "google",
    "medium": "cpc",
    "campaign": "summer-sale-2024",
    "term": "running shoes",
    "clickIds": {
      "fbclid": "IwAR2xK9..."
    }
  }
}

Fields:

source (string, optional): Marketing source (e.g., “google”, “facebook”)
medium (string, optional): Marketing medium (e.g., “cpc”, “email”, “social”)
campaign (string, optional): Campaign name
term (string, optional): Search term or keyword
content (string, optional): Ad or link variant, such as the value of utm_content
clickIds (object, optional): Click identifiers appended to the landing URL by ad networks and email/SMS platforms, keyed by parameter name (e.g., fbclid, gclid). Layers uses these to derive a click source when the link carries no UTMs.
referrer (string, optional): The site that linked the shopper to the storefront, as a host or full URL (e.g., “google.com”). Layers normalizes it to a lowercase host without www..
landingPath (string, optional): The storefront path the shopper first landed on this visit (e.g., “/collections/sale”). Layers removes the query string and fragment and keeps up to 512 characters.
channel (string, optional): The arrival channel. Layers derives this value on the server, see Arrival channel.

Click identifiers and derived click source

Ad networks append click identifiers to landing URLs even when the link was never tagged with UTMs. Send those identifiers in marketing.clickIds and Layers derives the originating network as marketing.clickSource. You can use the derived value in contextual conditions and analytics segmentation alongside the UTM fields. Layers uses the raw click identifiers only to derive clickSource. The identifier values themselves are not recorded in analytics events. Supported parameters and the network they resolve to:

Parameter	Network
`fbclid`	`meta`
`gclid`, `gbraid`, `wbraid`	`google`
`msclkid`	`microsoft`
`ttclid`	`tiktok`
`twclid`	`twitter`
`epik`	`pinterest`
`sccid`	`snapchat`
`rdt_cid`	`reddit`
`li_fat_id`	`linkedin`
`klcid`, `_kx`	`klaviyo`
`trk_msg`, `trk_contact`	`listrak`

Behavior:

Parameter names match case-insensitively (Snapchat’s ScCid resolves the same as sccid). Unknown keys are ignored.
When multiple identifiers are present, ad networks take precedence over the email/SMS platforms (Klaviyo, Listrak). A Klaviyo-tagged link shared and clicked on Facebook resolves to meta.
A value is only honored when it is a non-empty string of 512 characters or fewer. Invalid values are skipped without affecting the UTM fields.
Layers derives only the network and discards the raw identifier tokens. They are never stored or inspected beyond the checks above.
The derived value never overwrites marketing.source. Merchant-declared UTMs stay authoritative.
fbclid resolves to meta, not facebook, because it cannot distinguish a Facebook click from an Instagram one.

A click source is not proof of a paid ad. Meta, for example, appends fbclid to organic link clicks too, so Layers derives only the source and never infers marketing.medium. Targeting a specific ad still requires UTM-tagged links.

Arrival channel

Layers classifies every visit into one arrival channel, marketing.channel, from the other marketing fields. The Storefront Pixel captures the referring site and landing page at the start of each visit and sends them as marketing.referrer and marketing.landingPath. Classification always happens on the server, so the same visit gets the same channel in requests, tracking events, and orders.

Channel	Meaning
`organic_search`	Unpaid search engine results
`paid_search`	Paid search ads
`ai_assistant`	AI assistants such as ChatGPT
`social`	Social networks
`paid_social`	Paid social ads
`email`	Email campaigns
`sms`	SMS campaigns
`affiliate`	Affiliate links
`referral`	Any other linking site
`direct`	No UTMs, click identifiers, or outside referring site

Layers uses the first signal that applies:

UTMs: When source or medium is set, the channel follows the medium. For example, cpc maps to paid_search (or paid_social for social sources), email to email, sms to sms, affiliate to affiliate, organic to organic_search, and social to social. Other mediums map to referral, or to ai_assistant when the source is a known AI assistant. Mediums are matched case-insensitively, and common alternative spellings count as the same medium:

Medium you send	Treated as
`ppc`, `paid`, `cpcsearch`, `cpcshopping`, `cpcpmax`, `product_sync`	`cpc`
`paid_social`, `paid-social`, `paidsocial`, `social_paid`, `social-paid`, `socialads`	Paid social (`paid_social` channel)
`social media`, `organic social`	`social`
`text`, `push`, `rcs`	`sms`
`aff`, `influencer`, `partnership`	`affiliate`
`seo`	`organic`

Click identifiers: When the visit has a derived click source, the channel follows the network. Google and Microsoft map to paid_search, Meta to social, other ad networks to paid_social, and Klaviyo and Listrak to email.
Campaign only: When only campaign is set, Layers leaves the channel empty.
Referring site: Layers matches the referrer host against known search engines, AI assistants, social networks, and email providers. Visits referred by Android apps are recognized too: the Gmail app counts as email and the Google app counts as organic_search. Any other host is classified as referral.
Direct: When none of the above apply and the visit has a landing path, the channel is direct.

Behavior:

When the visit has no UTMs and the referring site is recognized, Layers also fills source and medium. A visit from Google search, for example, gets source google and medium organic. An unrecognized site gets its host as the source and referral as the medium. UTMs you send are never overwritten.
Your own storefront domains, including custom domains, and checkout and payment hosts are not treated as referring sites. A shopper who returns from checkout or moves between your domains doesn’t start a new referral.
A channel you send is kept only when Layers can’t derive one, and only if it’s one of the values above. Other values are dropped.
Tracking events get the same server-side channel and clickSource as requests, and their referring site is stored in the same normalized form, so www.google.com and google.com report as one referring site. A clickSource you send on an event is kept only when Layers can’t derive one, and only if it’s one of the supported networks above.
An order takes the channel of the visit it came from. When that visit has no channel, for example because the pixel didn’t record it, Layers classifies the order from its own UTM source, medium, and campaign using the same rules. The visit’s channel always wins over the order’s UTMs. An order with no UTMs is left without a channel instead of being counted as direct. An order’s click source always comes from its visit.

Experiments

The experiments object records which A/B test group the shopper is in for each running experiment. Keys are experiment IDs and values are group IDs.

{
  "experiments": {
    "exp_free_shipping": "variant_b"
  }
}

When Intelligems runs on the storefront, the Layers app embed reads the shopper’s current assignments and adds them to every search, browse, and block request. Assignments your storefront sends itself are merged in and win for the same experiment ID. Layers uses these values for the Experiment Group condition after you connect Intelligems under Settings → Integrations.

Customer profile

Aggregated customer behavior and purchase patterns for personalization.

{
  "customer": {
    "signedIn": true,
    "returning": true,
    "numberOfOrders": 5,
    "averageOrderValue": 125.50,
    "daysBetweenOrders": 45,
    "daysSinceLastOrder": 30,
    "daysSinceOldestOrder": 365,
    "totalSpent": 627.50,
    "tags": ["vip", "wholesale"]
  }
}

Fields:

signedIn (boolean, optional): Whether the customer is currently authenticated
returning (boolean, optional): Whether this is a returning customer
numberOfOrders (integer, optional): Total number of orders placed
averageOrderValue (float, optional): Average order value in store currency
daysBetweenOrders (integer, optional): Average days between orders
daysSinceLastOrder (integer, optional): Days since the most recent order
daysSinceOldestOrder (integer, optional): Days since the first order
totalSpent (float, optional): Total amount spent in store currency
tags (array of strings, optional): Shopify customer tags on the shopper’s profile. Collected by the Storefront Pixel for signed-in customers; null for guests. Available as context.customer.tags in contextual conditions.
segments (array of integers, server-resolved): Shopify customer segment IDs the shopper belongs to. Populated by Layers from the signed-in identity.customerId on every request; any client-supplied value is ignored. null for guests and customers with no segment memberships. Available as context.customer.segments in contextual conditions.

Market

Identifies the Shopify Market for the current request. Used for market-specific product availability filtering, contextual pricing, and market-targeted merchandising rules.

{
  "context": {
    "market": "US"
  }
}

Fields:

market (string, optional): The market identifier. Accepts a two-letter country code (e.g., "US", "CA"), a numeric Shopify Market ID (e.g., "12345"), a Shopify Market GID (e.g., "gid://shopify/Market/12345"), or a market handle.
marketId (number, optional): A direct active Shopify Market ID accepted by Search and Browse when no explicit market selector is sent. For Blocks, use market to select a market explicitly.

Resolution behavior: For Search and Browse, an explicit context.market (or top-level market when context.market is absent) takes precedence. With no explicit selector, Layers uses context.marketId if it names an active market, then the shopper’s country (via context.geo.country or request geolocation), then the active primary market. If an explicit selector doesn’t resolve, Layers falls back to country and primary market resolution without trying context.marketId. An unknown or inactive direct ID also falls back to country and primary market resolution. Layers resolves pricingCountryCode and baseCurrencyCode on the server and strips client-supplied values for those fields. Choose a market and supply the shopper’s country instead of setting these derived fields. The base currency determines the currency of fixed-amount discount entitlements. Once the market is resolved, Layers picks a pricing country inside that market, because prices are stored per country within a market. It checks, in order:

A country code in context.market. When context.market is a two-letter country code (for example, from a storefront market switcher) and that country belongs to the resolved market, Layers prices for that country. A deliberate country selection wins over the shopper’s detected location. For example, a shopper browsing from the US who selects Philippines receives PHP-denominated prices for the Philippines region of the resolved market.
The shopper’s country. Otherwise, Layers uses context.geo.country (or the IP-detected country) if it belongs to the resolved market.
A fallback country in the market. If neither applies (for example, the shopper is outside the market, or a server-side request omits geo.country so the detected country is your server’s), Layers uses the market’s only country for single-country markets, or the first country alphabetically by country code for multi-country markets.

A numeric Shopify Market ID or GID selects the market without naming a country, so pricing then resolves from step 2 or 3. For multi-country markets, send context.geo.country (or a country code in context.market) to make sure shoppers get their own country’s prices. Application modes: The store’s market application mode is set in the Layers dashboard under Settings > Search & Discovery > Search Behavior, in the Markets card. It controls how the resolved market affects results:

Restrict to market catalog: Only products available in the resolved market appear in results, and market-specific pricing is applied to variants
Adjust pricing only: All products remain visible, but variant prices are swapped to market-specific values where available
Ignore markets (default): Market resolution is skipped entirely; the base catalog and base pricing apply for all shoppers

See Shopify Markets for details on each mode. When market pricing is active, the price_range and variant price fields in API responses reflect the market-specific prices rather than the store’s base currency prices.

Session

Session-level signals about the current visit. Used for merchandising rules that adapt to new vs. returning sessions and for analytics segmentation.

{
  "session": {
    "returning": true
  }
}

Fields:

returning (boolean, optional): Whether the current session belongs to a returning visitor. Layers derives this from the storefront’s session cookie when not provided.

Locale

The active storefront locale for the request. Used for localized merchandising and analytics segmentation.

{
  "locale": "en"
}

Fields:

locale (string, optional): Storefront locale code (e.g., "en", "fr", "pt-br"). Case-insensitive; Layers normalizes to lowercase.

Currency

The currency applied to the request. Used for analytics segmentation and to ensure event data records the currency the shopper actually saw.

{
  "currency": "USD"
}

Fields:

currency (string, optional): ISO 4217 currency code (e.g., "USD", "EUR"). Case-insensitive; Layers normalizes to uppercase. When Layers can resolve a currency from the shopper’s market or pricing context, the server-resolved value takes precedence over the client-supplied one.

B2B company

The Shopify B2B company location associated with a signed-in company account. Used for B2B-specific merchandising, pricing, and analytics segmentation.

{
  "b2bCompany": "12345678"
}

Fields:

b2bCompany (string, optional): Shopify B2B company location identifier. When identity.companyLocationId is provided, Layers resolves the company location server-side and the server value takes precedence.

Device type

Use device type to target phones, desktop browsers, tablets, or bots in contextual conditions. Fields:

deviceType (string, optional): Accepts "mobile", "desktop", "tablet", or "bot". An explicit value takes precedence over automatic detection.

Layers detects device type from the request’s User-Agent when you omit it, even when you send no other context. For server-side integrations, pass the shopper’s device type explicitly so conditions don’t use your server’s user agent. If device information is unavailable, Layers leaves device type unset rather than assuming mobile or desktop. Tablets have their own category. Device type is independent of shopping channel: a phone browser can have device type "mobile" and shopping channel "web".

Shopping channel

Identifies the channel the customer is browsing from (web browser vs mobile app). Used for channel-specific merchandising rules, sorting, and analytics segmentation.

{
  "shoppingChannel": "web"
}

Fields:

shoppingChannel (string, optional): The shopping channel. Accepted values: "web" (default) or "app". When not provided, Layers detects the channel from request headers (e.g., mobile app requests via Fuego, Tapcart or Mobiloud Canvas are detected as "app").

Custom context

Additional custom contextual data specific to your implementation.

{
  "custom": {
    "loyaltyTier": "gold",
    "preferredBrand": "Nike",
    "customField": "value"
  }
}

The custom field accepts any arbitrary key-value pairs for implementation-specific context that doesn’t fit into the standard categories. Values can be scalars or objects nested one level deep (for example, "loyalty": { "tier": "platinum" }). The Storefront Pixel stamps several well-known keys into custom automatically:

page (string): The pathname of the storefront page that issued the request or event, for example /products/hat. Stamped at send time, so it always reflects the page the shopper was on.
query (object): The current page’s non-attribution query parameters (for example, { "filter.v.option.color": "red" }). Attribution and internal parameters (UTMs, ad click IDs, keys starting with _) are excluded, and recorded values are filtered for sensitive-looking content before storage (see Usage and privacy). A storefront can override or clear the captured params by setting custom.query explicitly.
clickedSection / clickedBlock (strings): The theme section and block IDs the shopper clicked on the previous page, reported once with the next page’s context. These power the Clicked Section and Clicked Block condition fields.

Layers automatically discovers the custom parameters your storefront sends and offers them as targetable fields in contextual condition builders across merchandising rules, banners, experiment audiences, sort orders, request transforms, and blocks. See Custom context fields for discovery requirements and timing.

Complete context example

This example shows every available context field:

{
  "identity": {
    "sessionId": "abc123xyz",
    "customerId": "gid://shopify/Customer/123456",
    "deviceId": "device-uuid-here"
  },
  "context": {
    "geo": {
      "country": "US",
      "province": "California",
      "city": "Los Angeles"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "price": "110.00",
        "type": "Shoes",
        "productId": "1234567890",
        "variantId": "9876543210",
        "options": {
          "Size": "11",
          "Color": "White"
        }
      }
    ],
    "productsViewed": [
      {
        "id": "1234567890",
        "at": 1721390400000,
        "title": "Nike Air Force 1",
        "type": "Shoes"
      }
    ],
    "productsPurchased": [
      {
        "title": "Nike Air Max 90",
        "price": "120.00",
        "type": "Shoes",
        "productId": "0987654321",
        "variantId": "1111111111",
        "options": {
          "Size": "11",
          "Color": "Black"
        }
      }
    ],
    "priorSearches": [
      {
        "searchQuery": "running shoes",
        "hadClick": true,
        "hasResults": true
      },
      {
        "searchQuery": "nike sneakers",
        "hadClick": false,
        "hasResults": true
      }
    ],
    "marketing": {
      "source": "google",
      "medium": "cpc",
      "campaign": "summer-sale-2024",
      "term": "running shoes"
    },
    "customer": {
      "signedIn": true,
      "returning": true,
      "numberOfOrders": 5,
      "averageOrderValue": 125.50,
      "daysBetweenOrders": 45,
      "daysSinceLastOrder": 30,
      "daysSinceOldestOrder": 365,
      "totalSpent": 627.50,
      "tags": ["vip", "wholesale"]
    },
    "market": "US",
    "shoppingChannel": "web",
    "session": {
      "returning": true
    },
    "locale": "en",
    "currency": "USD",
    "b2bCompany": "12345678",
    "custom": {
      "loyaltyTier": "gold",
      "preferredBrand": "Nike"
    }
  }
}

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Context data structure

Geographic information

Products in cart

Free shipping threshold

Recently viewed products

Purchase history

Prior searches

Marketing attribution

Click identifiers and derived click source

Arrival channel

Experiments

Customer profile

Market

Session

Locale

Currency

B2B company

Device type

Shopping channel

Custom context

Complete context example

​Geographic information

​Products in cart

​Free shipping threshold

​Recently viewed products

​Purchase history

​Prior searches

​Marketing attribution

​Click identifiers and derived click source

​Arrival channel

​Experiments

​Customer profile

​Market

​Session

​Locale

​Currency

​B2B company

​Device type

​Shopping channel

​Custom context

​Complete context example

Geographic information

Products in cart

Free shipping threshold

Recently viewed products

Purchase history

Prior searches

Marketing attribution

Click identifiers and derived click source

Arrival channel

Experiments

Customer profile

Market

Session

Locale

Currency

B2B company

Device type

Shopping channel

Custom context

Complete context example