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, required): Product title
price (string, optional): Product price as a string
type (string, optional): Product type
productId (string, optional): Shopify product ID
variantId (string, optional): Shopify variant ID
options (object, optional): Key-value pairs of variant options

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",
      "options": {
        "Size": "13",
        "Color": "Black"
      }
    }
  ]
}

Fields:

title (string, required): Product title
price (string, optional): Product price as a string
type (string, optional): Product type
productId (string, optional): Shopify product ID
variantId (string, optional): Shopify variant ID
options (object, optional): Key-value pairs of variant options

Prior searches

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

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

Fields:

searchQuery (string, required): The search query text
hadClick (boolean, required): Whether the customer clicked on any results
hadResults (boolean, required): Whether the search returned any results

Marketing attribution

UTM parameters and marketing campaign information for attribution tracking.

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

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

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
  }
}

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

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. When context.market is provided as a two-letter country code (for example, from a storefront market switcher), Layers uses that country as the pricing country ahead of IP-based geolocation. 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, rather than prices keyed to their IP geo. If the selected country isn’t a region of the resolved market, Layers falls back to geo-based resolution. Market selection by numeric Shopify Market ID or GID does not name a country, so pricing still resolves from geo in that case. Application modes: The store’s market application mode (configured in the Layers dashboard under Settings > Search & Discovery) controls how the resolved market affects results:

Strict — Only products available in the resolved market appear in results, and market-specific pricing is applied to variants
Pricing only — All products remain visible, but variant prices are swapped to market-specific values where available
Off — Market resolution is skipped entirely; the base catalog and base pricing apply for all shoppers

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 the platform 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, the platform automatically 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.

Complete context example

Here’s a comprehensive example showing all available contextual information fields:

{
  "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,
        "hadResults": true
      },
      {
        "searchQuery": "nike sneakers",
        "hadClick": false,
        "hadResults": 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
    },
    "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

Recently viewed products

Purchase history

Prior searches

Marketing attribution

Customer profile

Market

Session

Locale

Currency

B2B company

Shopping channel

Custom context

Complete context example

​Geographic information

​Products in cart

​Recently viewed products

​Purchase history

​Prior searches

​Marketing attribution

​Customer profile

​Market

​Session

​Locale

​Currency

​B2B company

​Shopping channel

​Custom context

​Complete context example

Geographic information

Products in cart

Recently viewed products

Purchase history

Prior searches

Marketing attribution

Customer profile

Market

Session

Locale

Currency

B2B company

Shopping channel

Custom context

Complete context example