Skip to main content
Layers uses lightweight session context to deliver personalized search experiences. By understanding what customers have viewed, purchased, searched for, and where they’re located, the platform can surface more relevant products and optimize merchandising decisions in real-time.

​
How Contextual Information Works

Contextual information is automatically collected and managed by the Storefront Pixel for standard Shopify integrations. For headless or custom implementations, you must manually include contextual data in your API requests to enable personalization features.

​
Standard Shopify Integration

When you install the Layers Storefront Pixel on your Shopify theme, contextual information is automatically:
  • Collected from the customer’s browsing session and Shopify customer data
  • Transmitted with every search, browse, and tracking event
  • Used to personalize results without any additional implementation

​
Headless Integration

For headless storefronts or custom implementations, you must:
  1. Collect relevant contextual information from your application
  2. Include it in the context parameter of your API requests
  3. Manage user identity through the identity parameter
  4. Pass geographic location explicitly when making server-side API calls (the platform cannot automatically determine location from server IP addresses)
See the Search API, Browse API, and Prepare Search API documentation for details on passing contextual information.

​
User Identity

Layers uses three identifiers to track and personalize user experiences:

​
Device ID (Browser ID)

A persistent identifier stored in the browser’s local storage that remains constant across sessions. This allows Layers to recognize returning visitors even when they’re not signed in, enabling long-term personalization and behavior tracking. Source: Generated by the Storefront Pixel on first visit and persisted in browser storage.

​
Session ID

A temporary identifier that represents a single browsing session. Sessions typically expire after a period of inactivity or when the user closes their browser (depending on Shopify’s session management). Source: Shopify session ID, available via Liquid template variables.

​
Customer ID

The Shopify customer ID for authenticated users. This identifier is only present when a customer is signed in to their account. Source: Shopify customer ID, available when customer exists in Liquid templates. These identifiers are included in the identity parameter when making API requests. The Storefront Pixel handles this automatically for standard integrations.

​
Contextual Data Structure

The context parameter accepts the following structured data:

​
Geographic Information

Location data used for regional merchandising and localized search results. For client-side requests, the platform automatically determines the user’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 user 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

​
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"
        }
      }
    ],
    "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
    },
    "custom": {
      "loyaltyTier": "gold",
      "preferredBrand": "Nike"
    }
  }
}

​
What Context Influences

Contextual information affects multiple aspects of the search experience: Relevance Scoring: Products related to cart items or purchase history receive adjusted relevance scores, surfacing complementary or similar items more prominently. Facet Selection: The platform intelligently selects which facets to display based on the customer’s browsing context and previous interactions. Sort Order Optimization: Default sorting can be influenced by customer behavior patterns, showing more relevant products first. Geographic Personalization: Location-aware merchandising rules and product availability can be applied based on the customer’s region. Intent Understanding: Prior searches and click behavior inform how new queries are interpreted, improving semantic understanding over time. Customer Segmentation: Customer profile data (order history, spending patterns, loyalty status) enables personalized experiences for different customer segments. Marketing Attribution: UTM parameters and campaign information help track the effectiveness of marketing efforts and can influence product recommendations.

​
Implementation Notes

  • Contextual information is processed in real-time and only persists for the duration of the session
  • No personally identifiable information (PII) is required; all data is behavioral and anonymous
  • Sort Orders and Merchandising Rules always take precedence over contextual adjustments
  • Missing or incomplete contextual data won’t break functionality; the platform gracefully degrades to non-personalized results
  • For headless implementations, validate your contextual data structure matches the expected format to ensure proper personalization

​
Privacy Considerations

The Layers platform is designed with privacy in mind:
  • Device IDs are anonymous browser identifiers, not tied to personal information
  • Contextual data is used only for search personalization and is not shared with third parties
  • Customer IDs are encrypted and handled according to Shopify’s privacy standards
  • Geographic data is limited to city-level granularity, never precise coordinates
See also: Storefront Pixel, User Intent Processing, Search API