Skip to main content
POST
https://app.uselayers.com/api/storefront/v1
/
search
/
{searchQuery}
/
prepare
Prepare Search: Async Search Optimization
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>"
  ],
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  },
  "context": {
    "geo": {
      "country": "<string>",
      "province": "<string>",
      "city": "<string>"
    },
    "productsInCart": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>"
      }
    ],
    "productsPurchased": [
      {
        "title": "<string>",
        "price": 123,
        "type": "<string>"
      }
    ],
    "priorSearches": [
      {
        "searchQuery": "<string>",
        "hadClick": true,
        "hasResults": true,
        "fromPage": "<string>"
      }
    ],
    "custom": {}
  }
}
'
{
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}
This endpoint prepares expensive parts of a search (embeddings and AI-powered query expansions) asynchronously for a given query, returning a ULID search_id that can be used with the Search API to execute with lower latency.
  • 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
​
Accept
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 Schema for detailed descriptions.
​
tuning
object
Parameters to fine-tune the search results.
​
filter_group
object
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
​
pagination
Pagination Object
​
facets
string[]
Facets to be included.
​
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.
​
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.

​
Behavior

  • Returns HTTP 202 (Accepted) immediately with a search_id
  • Generates a ULID search_id that identifies the prepared search
  • Dispatches an asynchronous background job on a high-priority queue
  • Pre-computes embeddings and AI-powered query expansions
  • Prepared data is cached for up to 5 minutes; after TTL, Search falls back to normal processing

​
Response

​
202 Accepted

​
search_id
string
ULID identifier for the prepared search. Valid for 5 minutes.
{
  "search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}

​
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.