Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

The context parameter accepts the following structured data:

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

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