Text Search: Prepare Search

curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "attributes": [
    "<string>"
  ],
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>",
    "companyLocationId": "<string>"
  },
  "context": {
    "geo": {
      "country": "<string>",
      "province": "<string>",
      "city": "<string>"
    },
    "productsInCart": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "productsPurchased": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "priorSearches": [
      {
        "searchQuery": "<string>",
        "hadClick": true,
        "hasResults": true,
        "fromPage": "<string>"
      }
    ],
    "marketing": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>"
    },
    "customer": {
      "signedIn": true,
      "returning": true,
      "numberOfOrders": 123,
      "averageOrderValue": 123,
      "daysBetweenOrders": 123,
      "daysSinceLastOrder": 123,
      "daysSinceOldestOrder": 123,
      "totalSpent": 123
    },
    "market": "<string>",
    "shoppingChannel": "<string>",
    "custom": {}
  }
}
'

POST /storefront/v1/search/running%20shoes/prepare

{
  "context": {
    "geo": {
      "country": "US",
      "province": "California"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "productId": "1234567890"
      }
    ],
    "marketing": {
      "source": "google",
      "medium": "cpc"
    },
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

POST

{searchQuery}

prepare

Text Search: Prepare Search

curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "attributes": [
    "<string>"
  ],
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>",
    "companyLocationId": "<string>"
  },
  "context": {
    "geo": {
      "country": "<string>",
      "province": "<string>",
      "city": "<string>"
    },
    "productsInCart": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "productsPurchased": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>",
        "productId": "<string>",
        "variantId": "<string>",
        "options": {}
      }
    ],
    "priorSearches": [
      {
        "searchQuery": "<string>",
        "hadClick": true,
        "hasResults": true,
        "fromPage": "<string>"
      }
    ],
    "marketing": {
      "source": "<string>",
      "medium": "<string>",
      "campaign": "<string>",
      "term": "<string>"
    },
    "customer": {
      "signedIn": true,
      "returning": true,
      "numberOfOrders": 123,
      "averageOrderValue": 123,
      "daysBetweenOrders": 123,
      "daysSinceLastOrder": 123,
      "daysSinceOldestOrder": 123,
      "totalSpent": 123
    },
    "market": "<string>",
    "shoppingChannel": "<string>",
    "custom": {}
  }
}
'

POST /storefront/v1/search/running%20shoes/prepare

{
  "context": {
    "geo": {
      "country": "US",
      "province": "California"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "productId": "1234567890"
      }
    ],
    "marketing": {
      "source": "google",
      "medium": "cpc"
    },
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

This endpoint asynchronously prepares expensive personalization for a given query, returning a ULID search_id that can be used with the Search API to execute the search.

Use with: Search API via the search_id body parameter

Authorization

X-Storefront-Access-Token

string

required

Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>. Same requirements as the Search API.

Headers

Content-Type

string

default:"application/json"

required

string

default:"application/json"

required

Path parameters

searchQuery

string

required

The url-encoded search query to prepare.

Body

attributes

string[]

Optional hint for which product attributes you intend to include in the eventual Search response. Available attributes include: id, title, handle, body_html, vendor, product_type, tags, images, available, created_at, updated_at, published_at, price_range, options, original_options, metafields, named_tags, calculated, category, featured_media, is_gift_card, has_variants_that_require_components, combined_listing_parent_product_id, combined_listing_role, and first_or_matched_variant. See the Product Schemafor detailed descriptions.

filter_group

object

Refer to our dedicated Filter Expressions guide to learn more about filter expressions.

pagination

Pagination Object

Show pagination

page

int

The current page of results to fetch.

limit

int

The max results to fetch per page

facets

string[]

Facets to be included. Accepts both exact facet codes (e.g., "vendor", "options.Size") and wildcard patterns (e.g., "options.*", "metafields.product.*").Wildcard patterns expand to all matching attribute codes. For example, "options.*" expands to all option facets like "options.Size" and "options.Color". Wildcards must match at least one attribute code to be valid.Examples:

// Exact facet codes
"facets": ["vendor", "options.Size", "options.Color"]

// Wildcard pattern
"facets": ["options.*"]

// Mixed exact and wildcard
"facets": ["vendor", "options.*", "metafields.product.*"]

retrieveFacetCount

boolean

If the count of each facet value should be calculated

includeFacetRanges

boolean

If you want a min/max range for numeric facets such as price.

identity

object

User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.

Show Properties

deviceId

string

Persistent browser identifier that remains constant across sessions. Used to recognize returning visitors for long-term personalization. Automatically generated and managed by the Storefront Pixel.

sessionId

string

Temporary session identifier. Typically corresponds to the Shopify session ID and expires after inactivity or when the browser is closed.

customerId

string

Shopify customer ID for authenticated users. Only present when the user is signed in to their account.

companyLocationId

string

Shopify B2B company location GID (e.g. gid://shopify/CompanyLocation/123456789) for the authenticated buyer. Layers resolves the catalog assigned to the company location and uses it to scope results: only products in the catalog are returned, prices come from the catalog’s price list, and excluded collections return 404. Omit for retail (DTC) traffic. See B2B catalogs.

context

object

Contextual information about the customer’s session, behavior, and environment. Automatically collected by the Storefront Pixel; must be manually provided for headless integrations. See Contextual Information for implementation guidance.

Show Properties

geo

object

Geographic location information for regional personalization and merchandising. Automatically determined by the platform for client-side requests based on IP address. For server-side API calls (headless integrations), you should provide this explicitly.

Show Properties

country

string

Country code or name (e.g., “US”, “Canada”).

province

string

State or province name (e.g., “California”, “Ontario”).

city

string

City name (e.g., “Los Angeles”, “Toronto”).

productsInCart

array

Products currently in the customer’s cart. Used to surface complementary products and influence relevance scoring.

Show Array Item Properties

title

string

required

Product title.

price

number

Product price.

type

string

Product type or category.

productId

string

Product identifier. Accepts a numeric ID (e.g., "8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").

variantId

string

Product variant identifier.

options

object

Product variant options (e.g., {"Size": "11", "Color": "Red"}).

productsPurchased

array

Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.

Show Array Item Properties

title

string

required

Product title.

price

number

Product price at time of purchase.

type

string

Product type or category.

productId

string

Product identifier. Accepts a numeric ID (e.g., "8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").

variantId

string

Product variant identifier.

options

object

Product variant options (e.g., {"Size": "11", "Color": "Red"}).

priorSearches

array

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

Show Array Item Properties

searchQuery

string

required

The search query text.

hadClick

boolean

required

Whether the customer clicked on any results from this search.

hasResults

boolean

required

Whether the search returned any results.

fromPage

string

The page the search was initiated from (e.g., the referring page URL or page type).

marketing

object

UTM parameters and marketing campaign information for attribution tracking.

Show Properties

source

string

Marketing source (e.g., “google”, “facebook”).

medium

string

Marketing medium (e.g., “cpc”, “email”, “social”).

campaign

string

Campaign name.

term

string

Search term or keyword.

customer

object

Aggregated customer behavior and purchase patterns for personalization.

Show Properties

signedIn

boolean

Whether the customer is currently authenticated.

returning

boolean

Whether this is a returning customer.

numberOfOrders

integer

Total number of orders placed.

averageOrderValue

number

Average order value in store currency.

daysBetweenOrders

integer

Average days between orders.

daysSinceLastOrder

integer

Days since the most recent order.

daysSinceOldestOrder

integer

Days since the first order.

totalSpent

number

Total amount spent in store currency.

market

string

Explicitly set the Shopify Market for this request. Used for market-specific product availability filtering and contextual pricing. 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").When not provided, the market is automatically resolved from the geo.country field (or the shopper’s detected country for client-side requests). If no matching market is found, the store’s primary market is used as the fallback.Behavior depends on the store’s market application mode:

Strict — Products are filtered to only those available in the resolved market, and market-specific pricing is applied
Pricing only — The full catalog remains visible, but variant prices are swapped to market-specific values where available
Off — Market resolution is skipped entirely; base catalog and base pricing are used for all shoppers

shoppingChannel

string

default:"web"

The shopping channel the customer is browsing from. Used for channel-specific merchandising, sorting, and analytics segmentation. Automatically detected from request headers when not provided (e.g., mobile app requests via Tapcart or Canvas are detected as "app").Accepted values:

"web" — Standard web browser (default)
"app" — Mobile app (e.g., Tapcart, Canvas)

custom

object

Custom contextual data specific to your implementation. Structure is flexible and can contain any key-value pairs relevant to your use case.

Behavior

Returns HTTP 202 (Accepted) immediately with a search_id
Generates a ULID search_id that identifies the prepared search
Starts additional search preparation asynchronously
Pre-computes query understanding and personalization inputs
Prepared data is cached for up to 15 minutes; after TTL, Search falls back to normal processing

Response

202 Accepted

search_id

string

ULID identifier for the prepared search. Valid for 15 minutes.

POST /storefront/v1/search/running%20shoes/prepare

{
  "context": {
    "geo": {
      "country": "US",
      "province": "California"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "productId": "1234567890"
      }
    ],
    "marketing": {
      "source": "google",
      "medium": "cpc"
    },
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

Response headers

Header	Description
`x-request-id`	A unique identifier (ULID) for the request. Use it to correlate requests across your infrastructure or when contacting support.
`x-layers-build`	The Layers build version that served the request.

Error conditions

401 Unauthorized: Missing/invalid X-Storefront-Access-Token
422 Unprocessable Entity: Invalid body or parameters

Next steps

Use the returned search_id with the Search API in the search_id body parameter to execute an optimized search.

Collection Page Execute Search

⌘I

Documentation Index

​Authorization

​Headers

​Path parameters

​Body

​Behavior

​Response

​202 Accepted

​Response headers

​Error conditions

​Next steps

Authorization

Headers

Path parameters

Body

Behavior

Response

202 Accepted

Response headers

Error conditions

Next steps