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,
"enrichFacetMetaobjects": 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": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<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>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": true,
"returning": true,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [
{}
],
"segments": [
{}
]
},
"market": "<string>",
"session": {
"returning": true
},
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare"
payload = {
"attributes": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"enrichFacetMetaobjects": 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": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<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>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": True,
"returning": True,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [{}],
"segments": [{}]
},
"market": "<string>",
"session": { "returning": True },
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
}
}
headers = {
"X-Storefront-Access-Token": "<x-storefront-access-token>",
"Content-Type": "<content-type>",
"Accept": "<accept>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Storefront-Access-Token': '<x-storefront-access-token>',
'Content-Type': '<content-type>',
Accept: '<accept>'
},
body: JSON.stringify({
attributes: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
enrichFacetMetaobjects: 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: {},
quantity: 123
}
],
freeShippingThreshold: 123,
productsViewed: [
{
id: '<string>',
at: 123,
title: '<string>',
type: '<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>',
content: '<string>',
clickIds: {},
referrer: '<string>',
landingPath: '<string>',
channel: '<string>'
},
experiments: {},
customer: {
signedIn: true,
returning: true,
numberOfOrders: 123,
averageOrderValue: 123,
daysBetweenOrders: 123,
daysSinceLastOrder: 123,
daysSinceOldestOrder: 123,
totalSpent: 123,
tags: [{}],
segments: [{}]
},
market: '<string>',
session: {returning: true},
locale: '<string>',
currency: '<string>',
b2bCompany: '<string>',
shoppingChannel: '<string>',
custom: {}
}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'attributes' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'enrichFacetMetaobjects' => 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' => [
],
'quantity' => 123
]
],
'freeShippingThreshold' => 123,
'productsViewed' => [
[
'id' => '<string>',
'at' => 123,
'title' => '<string>',
'type' => '<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>',
'content' => '<string>',
'clickIds' => [
],
'referrer' => '<string>',
'landingPath' => '<string>',
'channel' => '<string>'
],
'experiments' => [
],
'customer' => [
'signedIn' => true,
'returning' => true,
'numberOfOrders' => 123,
'averageOrderValue' => 123,
'daysBetweenOrders' => 123,
'daysSinceLastOrder' => 123,
'daysSinceOldestOrder' => 123,
'totalSpent' => 123,
'tags' => [
[
]
],
'segments' => [
[
]
]
],
'market' => '<string>',
'session' => [
'returning' => true
],
'locale' => '<string>',
'currency' => '<string>',
'b2bCompany' => '<string>',
'shoppingChannel' => '<string>',
'custom' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Accept: <accept>",
"Content-Type: <content-type>",
"X-Storefront-Access-Token: <x-storefront-access-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare"
payload := strings.NewReader("{\n \"attributes\": [\n \"<string>\"\n ],\n \"filter_group\": {},\n \"pagination\": {\n \"page\": 123,\n \"limit\": 123\n },\n \"facets\": [\n \"<string>\"\n ],\n \"retrieveFacetCount\": true,\n \"includeFacetRanges\": true,\n \"enrichFacetMetaobjects\": true,\n \"identity\": {\n \"deviceId\": \"<string>\",\n \"sessionId\": \"<string>\",\n \"customerId\": \"<string>\",\n \"companyLocationId\": \"<string>\"\n },\n \"context\": {\n \"geo\": {\n \"country\": \"<string>\",\n \"province\": \"<string>\",\n \"city\": \"<string>\"\n },\n \"productsInCart\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {},\n \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Storefront-Access-Token", "<x-storefront-access-token>")
req.Header.Add("Content-Type", "<content-type>")
req.Header.Add("Accept", "<accept>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"attributes\": [\n \"<string>\"\n ],\n \"filter_group\": {},\n \"pagination\": {\n \"page\": 123,\n \"limit\": 123\n },\n \"facets\": [\n \"<string>\"\n ],\n \"retrieveFacetCount\": true,\n \"includeFacetRanges\": true,\n \"enrichFacetMetaobjects\": true,\n \"identity\": {\n \"deviceId\": \"<string>\",\n \"sessionId\": \"<string>\",\n \"customerId\": \"<string>\",\n \"companyLocationId\": \"<string>\"\n },\n \"context\": {\n \"geo\": {\n \"country\": \"<string>\",\n \"province\": \"<string>\",\n \"city\": \"<string>\"\n },\n \"productsInCart\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {},\n \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Storefront-Access-Token"] = '<x-storefront-access-token>'
request["Content-Type"] = '<content-type>'
request["Accept"] = '<accept>'
request.body = "{\n \"attributes\": [\n \"<string>\"\n ],\n \"filter_group\": {},\n \"pagination\": {\n \"page\": 123,\n \"limit\": 123\n },\n \"facets\": [\n \"<string>\"\n ],\n \"retrieveFacetCount\": true,\n \"includeFacetRanges\": true,\n \"enrichFacetMetaobjects\": true,\n \"identity\": {\n \"deviceId\": \"<string>\",\n \"sessionId\": \"<string>\",\n \"customerId\": \"<string>\",\n \"companyLocationId\": \"<string>\"\n },\n \"context\": {\n \"geo\": {\n \"country\": \"<string>\",\n \"province\": \"<string>\",\n \"city\": \"<string>\"\n },\n \"productsInCart\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {},\n \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n }\n}"
response = http.request(request)
puts response.read_bodyPOST /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"
}
}
{
"search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}
Text Search
Text Search: Prepare Search
Prepare Search API endpoint that starts a search asynchronously so personalization and ranking can run in the background during a redirect or page load.
POST
/
search
/
{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,
"enrichFacetMetaobjects": 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": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<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>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": true,
"returning": true,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [
{}
],
"segments": [
{}
]
},
"market": "<string>",
"session": {
"returning": true
},
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare"
payload = {
"attributes": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"enrichFacetMetaobjects": 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": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<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>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": True,
"returning": True,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [{}],
"segments": [{}]
},
"market": "<string>",
"session": { "returning": True },
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
}
}
headers = {
"X-Storefront-Access-Token": "<x-storefront-access-token>",
"Content-Type": "<content-type>",
"Accept": "<accept>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Storefront-Access-Token': '<x-storefront-access-token>',
'Content-Type': '<content-type>',
Accept: '<accept>'
},
body: JSON.stringify({
attributes: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
enrichFacetMetaobjects: 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: {},
quantity: 123
}
],
freeShippingThreshold: 123,
productsViewed: [
{
id: '<string>',
at: 123,
title: '<string>',
type: '<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>',
content: '<string>',
clickIds: {},
referrer: '<string>',
landingPath: '<string>',
channel: '<string>'
},
experiments: {},
customer: {
signedIn: true,
returning: true,
numberOfOrders: 123,
averageOrderValue: 123,
daysBetweenOrders: 123,
daysSinceLastOrder: 123,
daysSinceOldestOrder: 123,
totalSpent: 123,
tags: [{}],
segments: [{}]
},
market: '<string>',
session: {returning: true},
locale: '<string>',
currency: '<string>',
b2bCompany: '<string>',
shoppingChannel: '<string>',
custom: {}
}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'attributes' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'enrichFacetMetaobjects' => 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' => [
],
'quantity' => 123
]
],
'freeShippingThreshold' => 123,
'productsViewed' => [
[
'id' => '<string>',
'at' => 123,
'title' => '<string>',
'type' => '<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>',
'content' => '<string>',
'clickIds' => [
],
'referrer' => '<string>',
'landingPath' => '<string>',
'channel' => '<string>'
],
'experiments' => [
],
'customer' => [
'signedIn' => true,
'returning' => true,
'numberOfOrders' => 123,
'averageOrderValue' => 123,
'daysBetweenOrders' => 123,
'daysSinceLastOrder' => 123,
'daysSinceOldestOrder' => 123,
'totalSpent' => 123,
'tags' => [
[
]
],
'segments' => [
[
]
]
],
'market' => '<string>',
'session' => [
'returning' => true
],
'locale' => '<string>',
'currency' => '<string>',
'b2bCompany' => '<string>',
'shoppingChannel' => '<string>',
'custom' => [
]
]
]),
CURLOPT_HTTPHEADER => [
"Accept: <accept>",
"Content-Type: <content-type>",
"X-Storefront-Access-Token: <x-storefront-access-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare"
payload := strings.NewReader("{\n \"attributes\": [\n \"<string>\"\n ],\n \"filter_group\": {},\n \"pagination\": {\n \"page\": 123,\n \"limit\": 123\n },\n \"facets\": [\n \"<string>\"\n ],\n \"retrieveFacetCount\": true,\n \"includeFacetRanges\": true,\n \"enrichFacetMetaobjects\": true,\n \"identity\": {\n \"deviceId\": \"<string>\",\n \"sessionId\": \"<string>\",\n \"customerId\": \"<string>\",\n \"companyLocationId\": \"<string>\"\n },\n \"context\": {\n \"geo\": {\n \"country\": \"<string>\",\n \"province\": \"<string>\",\n \"city\": \"<string>\"\n },\n \"productsInCart\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {},\n \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Storefront-Access-Token", "<x-storefront-access-token>")
req.Header.Add("Content-Type", "<content-type>")
req.Header.Add("Accept", "<accept>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"attributes\": [\n \"<string>\"\n ],\n \"filter_group\": {},\n \"pagination\": {\n \"page\": 123,\n \"limit\": 123\n },\n \"facets\": [\n \"<string>\"\n ],\n \"retrieveFacetCount\": true,\n \"includeFacetRanges\": true,\n \"enrichFacetMetaobjects\": true,\n \"identity\": {\n \"deviceId\": \"<string>\",\n \"sessionId\": \"<string>\",\n \"customerId\": \"<string>\",\n \"companyLocationId\": \"<string>\"\n },\n \"context\": {\n \"geo\": {\n \"country\": \"<string>\",\n \"province\": \"<string>\",\n \"city\": \"<string>\"\n },\n \"productsInCart\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {},\n \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/prepare")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Storefront-Access-Token"] = '<x-storefront-access-token>'
request["Content-Type"] = '<content-type>'
request["Accept"] = '<accept>'
request.body = "{\n \"attributes\": [\n \"<string>\"\n ],\n \"filter_group\": {},\n \"pagination\": {\n \"page\": 123,\n \"limit\": 123\n },\n \"facets\": [\n \"<string>\"\n ],\n \"retrieveFacetCount\": true,\n \"includeFacetRanges\": true,\n \"enrichFacetMetaobjects\": true,\n \"identity\": {\n \"deviceId\": \"<string>\",\n \"sessionId\": \"<string>\",\n \"customerId\": \"<string>\",\n \"companyLocationId\": \"<string>\"\n },\n \"context\": {\n \"geo\": {\n \"country\": \"<string>\",\n \"province\": \"<string>\",\n \"city\": \"<string>\"\n },\n \"productsInCart\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {},\n \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n }\n}"
response = http.request(request)
puts response.read_bodyPOST /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"
}
}
{
"search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}
This endpoint asynchronously prepares expensive personalization for a given query, returning a ULID
search_id that you can use with the Search API to execute the search.
- Use with: Search API via the
search_idbody parameter
Authorization
string
required
Token-based authentication header in the form of
<YOUR_LAYERS_TOKEN>. Same requirements as the Search API.Headers
string
default:"application/json"
required
string
default:"application/json"
required
Path parameters
string
required
The url-encoded search query to prepare. Layers normalizes the query before validating it, stripping invisible characters and converting Unicode punctuation to ASCII equivalents. After normalization, the query must be 2 to 255 characters. Queries outside this range return HTTP 422.
Body
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.object
Storefront endpoints accept nested
AND/OR filter groups up to two levels deep. Each nested group must contain at least one expression; empty nested groups are rejected. Metafield filter properties may include hyphens in their namespace or key, for example metafields.my-app.fit-type.Refer to the dedicated Filter Expressions guide to learn more about filter expressions.Pagination Object
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.*"]
boolean
If the count of each facet value should be calculated.
boolean
If you want a min/max range for numeric facets such as price.
boolean
When
true, any facet backed by a metaobject_reference or list.metaobject_reference metafield is returned with a companion facetDisplay object. Each entry maps a facet value (the metaobject handle) to the referenced metaobject’s display_name and fields. When the metaobject defines a color or image field, the entry also carries a resolved swatch object.Use this when your storefront filter UI needs human-readable labels or nested field data (for example, a color name or swatch hex) instead of the raw handle. When false or omitted, only the handles are returned in facets.Values are looked up from the local metaobject cache. Handles with no matching cached metaobject are omitted from facetDisplay and remain as plain values in facets. See Metaobjects and reference metafields for the normalized shape of each entry.object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
Show Properties
Show Properties
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.
string
Temporary session identifier. Layers-generated sessions expire after 30 minutes without activity. The Storefront Pixel refreshes the rolling window at page load and on every route change, including pages without tracked events. When a legacy Shopify or fallback cookie is available, Layers prefers it and does not control its lifetime. Without consent, the pixel uses a sessionStorage or in-memory fallback and does not write an analytics cookie.
string
Shopify customer ID for authenticated users. Only present when the customer is signed in to their account.
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.When you pass companyLocationId, you must also pass the buyer’s customerId. Layers verifies with Shopify that the customer belongs to the company that owns the location before resolving the catalog; unauthorized or unauthenticated requests return a 403. See B2B catalogs.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
Show Properties
object
Geographic location information for regional personalization and merchandising. Layers determines it from the IP address for client-side requests. For server-side API calls (headless integrations), provide
geo explicitly.array
Products currently in the customer’s cart. Used to surface complementary products and influence relevance scoring.
Show Array Item Properties
Show Array Item Properties
string
Product title. Each entry needs at least a
productId, variantId, or non-empty title. Layers drops entries with none of these.number
Unit price in the request currency’s major units (e.g.
29.00 for $29), not cents. Accepts a JSON number or a numeric string such as "29.00".string
Product type or category.
string
Product identifier. Accepts a numeric ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").string
Product variant identifier.
object
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).integer
Number of units of this line in the cart. Layers rounds fractional values down to a whole number. Missing values, non-numeric values, and values below
1 count as 1. Layers uses it to calculate the cart subtotal for Free Shipping Picks.number
The cart subtotal at which the shopper qualifies for free shipping, in the request currency’s major units (e.g.
75.00 for $75), not cents. Layers ignores values that aren’t a number greater than 0. Required for Free Shipping Picks blocks.Shopify’s
/cart.js and Liquid money values such as cart.total_price and item.price are in cents. Divide them by 100 before sending productsInCart[].price or freeShippingThreshold.array
Products the shopper has viewed during the current session. Layers uses these as short-lived personalization signals, with recent views weighted more heavily. Only the 20 most recent views are used. The Storefront Pixel populates this automatically; send it manually only for headless integrations. See Recently viewed products.
Show Array Item Properties
Show Array Item Properties
string
Product identifier. Accepts a numeric ID or a Shopify GID. Also accepted as
productId.integer
Timestamp of the view in Unix milliseconds. Views without
at still count but skip recency weighting.string
Product title.
string
Product type or category.
string
Variant identifier, if the shopper viewed a specific variant.
object
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).array
Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.
Show Array Item Properties
Show Array Item Properties
string
Product title. Each entry needs at least a
productId, variantId, or non-empty title. Layers drops entries with none of these.number
Unit price in the request currency’s major units (e.g.
29.00 for $29), not cents, at time of purchase. Accepts a JSON number or a numeric string such as "29.00".string
Product type or category.
string
Product identifier. Accepts a numeric ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").string
Product variant identifier.
object
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).array
Recent search queries and their outcomes. Helps understand customer intent and refine relevance models.
Show Array Item Properties
Show Array Item Properties
string
required
The search query text.
boolean
default:"false"
Whether the customer clicked on any results from this search.
boolean
default:"false"
Whether the search returned any results.
string
The page the search was started from (e.g., the referring page URL or page type). Layers accepts this field but doesn’t currently use it for ranking or rules.
object
UTM parameters and marketing campaign information for attribution tracking.
Show Properties
Show Properties
string
Marketing source (e.g., “google”, “facebook”).
string
Marketing medium (e.g., “cpc”, “email”, “social”).
string
Campaign name.
string
Search term or keyword.
string
Ad or link variant, such as the value of
utm_content.object
Click identifiers from the landing URL, keyed by parameter name (e.g.,
fbclid, gclid). Layers derives the originating network from them as marketing.clickSource and discards the raw tokens. See Context data structure.string
Host or URL of the site that linked the shopper to the storefront (e.g., “google.com”). Layers normalizes it to a lowercase host without
www..string
Storefront path the shopper first landed on this visit (e.g., “/collections/sale”). Layers removes the query string and keeps up to 512 characters.
string
Arrival channel. Layers derives it from UTMs, click identifiers, and the referring site, and keeps a value you send only when it can’t derive one. See Arrival channel.
object
A/B test assignments for the shopper, keyed by experiment ID with the assigned group ID as the value (e.g.,
{"exp_123": "group_b"}). Used by the Experiment Group contextual condition. The Layers app embed fills this from Intelligems automatically; values your storefront sends for the same experiment take precedence. Entries whose value isn’t a string are dropped.object
Aggregated customer behavior and purchase patterns for personalization.
Show Properties
Show Properties
boolean
Whether the customer is currently authenticated.
boolean
Whether this is a returning customer.
integer
Total number of orders placed.
number
Average order value in store currency.
integer
Average days between orders.
integer
Days since the most recent order.
integer
Days since the first order.
number
Total amount spent in store currency.
array
Shopify customer tags on the shopper’s profile (e.g.,
["vip", "wholesale"]). Collected by the Storefront Pixel for signed-in customers; null for guests.array
Shopify customer segment IDs the shopper belongs to. Server-resolved: Layers populates this from the signed-in
identity.customerId on every request and ignores any value you send. null for guests and customers with no segment memberships. Available as context.customer.segments in contextual conditions.string
Explicitly set the Shopify Market for this request. Must be provided inside
context; it is not a top-level request body parameter. 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 context.geo.country (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.When you send a two-letter country code that belongs to the resolved market, Layers also prices for that country, ahead of the shopper’s detected location. See Market resolution.Behavior depends on the store’s market application mode (set under Settings > Search & Discovery > Search Behavior, in the Markets card):- Restrict to market catalog — Products are filtered to only those available in the resolved market, and market-specific pricing is applied
- Adjust pricing only — The full catalog remains visible, but variant prices are swapped to market-specific values where available
- Ignore markets (default) — Market resolution is skipped entirely; base catalog and base pricing are used for all shoppers
object
Session-level signals about the current visit.
Show Properties
Show Properties
boolean
Whether the current session belongs to a returning visitor. Layers derives this from the storefront’s session cookie when not provided.
string
Storefront locale code (e.g.,
"en", "fr", "pt-br"). Case-insensitive; Layers normalizes to lowercase. When the locale is published in Shopify and served by the resolved market, Layers returns translated display text (titles, descriptions, option values, filter labels) while IDs, prices, and filter values stay in the source language. Regional locales fall back to their base language (pt-br uses pt). The store’s primary locale returns source text. See Translations.string
ISO 4217 currency code (e.g.,
"USD", "EUR"). Case-insensitive; Layers normalizes to uppercase. When Layers can resolve a currency from the shopper’s market or pricing context, the server-resolved value takes precedence.string
Shopify B2B company location identifier. When
identity.companyLocationId is provided, Layers resolves the company location server-side and the server value takes precedence.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, Fuego, or Mobiloud Canvas are detected as
"app").Accepted values:"web"— Standard web browser (default)"app"— Mobile app (e.g., Tapcart, Fuego, Mobiloud Canvas)
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_idthat 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
- If Layers is temporarily serving keyword-only results platform-wide, prepare still returns 202 with a usable
search_idbut skips semantic preparation. The execute call then returns keyword-only results with_meta.search_laneset to"prefix_only". No client changes are required.
Response
202 Accepted
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"
}
}
{
"search_id": "01HZY7J9ZV6K2T3M6P4FJ3F2QG"
}
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 - 402 Payment Required: The store is suspended. Every storefront API request returns this status until the suspension is lifted
- 422 Unprocessable Entity: Invalid body or parameters
Next steps
Use the returnedsearch_id with the Search API in the search_id body parameter to execute an optimized search.Was this page helpful?