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": {}
}
],
"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": {}
}
}
'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": {}
}
],
"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": {}
}
}
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: {}
}
],
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: {}
}
})
};
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' => [
]
]
],
'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' => [
]
]
]),
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 }\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 },\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 },\n \"market\": \"<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 }\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 },\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 },\n \"market\": \"<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 }\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 },\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 },\n \"market\": \"<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": {}
}
],
"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": {}
}
}
'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": {}
}
],
"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": {}
}
}
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: {}
}
],
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: {}
}
})
};
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' => [
]
]
],
'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' => [
]
]
]),
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 }\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 },\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 },\n \"market\": \"<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 }\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 },\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 },\n \"market\": \"<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 }\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 },\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 },\n \"market\": \"<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 can be used 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.
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 Schemafor detailed descriptions.object
Refer to our 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.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. Typically corresponds to the Shopify session ID and expires after inactivity or when the browser is closed.
string
Shopify customer ID for authenticated users. Only present when the user 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. 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.
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
required
Product title.
number
Product price.
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
Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.
Show Array Item Properties
Show Array Item Properties
string
required
Product title.
number
Product price at time of purchase.
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.
object
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.
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.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
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)
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
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 - 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?
⌘I