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.

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.

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"), or a Shopify Market GID (e.g., "gid://shopify/Market/12345").

Resolution behavior: When context.market is not provided, Layers automatically resolves the market from the shopper’s country (via context.geo.country or IP-based geolocation for client-side requests). If no matching market is found, the store’s primary market is used as a fallback. 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.

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

Customer profile

Market

Session

Locale

Currency

B2B company

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

​Customer profile

​Market

​Session

​Locale

​Currency

​B2B company

​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

Customer profile

Market

Session

Locale

Currency

B2B company

Shopping channel

Custom context

Complete context example