Search API: Similar Products
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId} \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '
{
"variant_id": 123,
"attributes": [
"<string>"
],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": [
"<string>"
],
"retrieveFacetCount": true,
"includeFacetRanges": true,
"enrichFacetMetaobjects": true,
"sort_order_code": "<string>",
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"discountEntitlements": [
{
"entitled": {
"all": true,
"products": [
"<string>"
],
"variants": [
{}
],
"collections": [
"<string>"
],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"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": {}
},
"responseOptions": {
"mediaPreloads": {
"enabled": true,
"srcsetSizes": [
123
],
"sizes": "<string>"
}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId}"
payload = {
"variant_id": 123,
"attributes": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"enrichFacetMetaobjects": True,
"sort_order_code": "<string>",
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"discountEntitlements": [
{
"entitled": {
"all": True,
"products": ["<string>"],
"variants": [{}],
"collections": ["<string>"],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"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": {}
},
"responseOptions": { "mediaPreloads": {
"enabled": True,
"srcsetSizes": [123],
"sizes": "<string>"
} }
}
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({
variant_id: 123,
attributes: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
enrichFacetMetaobjects: true,
sort_order_code: '<string>',
defaultSelectedOptions: [{optionCode: '<string>', value: '<string>'}],
discountEntitlements: [
{
entitled: {
all: true,
products: ['<string>'],
variants: [{}],
collections: ['<string>'],
conditions: {}
},
discount: {type: '<string>', value: 123}
}
],
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: {}
},
responseOptions: {mediaPreloads: {enabled: true, srcsetSizes: [123], sizes: '<string>'}}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId}', 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/product/{searchProductId}",
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([
'variant_id' => 123,
'attributes' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'enrichFacetMetaobjects' => true,
'sort_order_code' => '<string>',
'defaultSelectedOptions' => [
[
'optionCode' => '<string>',
'value' => '<string>'
]
],
'discountEntitlements' => [
[
'entitled' => [
'all' => true,
'products' => [
'<string>'
],
'variants' => [
[
]
],
'collections' => [
'<string>'
],
'conditions' => [
]
],
'discount' => [
'type' => '<string>',
'value' => 123
]
]
],
'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' => [
]
],
'responseOptions' => [
'mediaPreloads' => [
'enabled' => true,
'srcsetSizes' => [
123
],
'sizes' => '<string>'
]
]
]),
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/product/{searchProductId}"
payload := strings.NewReader("{\n \"variant_id\": 123,\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 \"sort_order_code\": \"<string>\",\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"discountEntitlements\": [\n {\n \"entitled\": {\n \"all\": true,\n \"products\": [\n \"<string>\"\n ],\n \"variants\": [\n {}\n ],\n \"collections\": [\n \"<string>\"\n ],\n \"conditions\": {}\n },\n \"discount\": {\n \"type\": \"<string>\",\n \"value\": 123\n }\n }\n ],\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 \"responseOptions\": {\n \"mediaPreloads\": {\n \"enabled\": true,\n \"srcsetSizes\": [\n 123\n ],\n \"sizes\": \"<string>\"\n }\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/product/{searchProductId}")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"variant_id\": 123,\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 \"sort_order_code\": \"<string>\",\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"discountEntitlements\": [\n {\n \"entitled\": {\n \"all\": true,\n \"products\": [\n \"<string>\"\n ],\n \"variants\": [\n {}\n ],\n \"collections\": [\n \"<string>\"\n ],\n \"conditions\": {}\n },\n \"discount\": {\n \"type\": \"<string>\",\n \"value\": 123\n }\n }\n ],\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 \"responseOptions\": {\n \"mediaPreloads\": {\n \"enabled\": true,\n \"srcsetSizes\": [\n 123\n ],\n \"sizes\": \"<string>\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId}")
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 \"variant_id\": 123,\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 \"sort_order_code\": \"<string>\",\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"discountEntitlements\": [\n {\n \"entitled\": {\n \"all\": true,\n \"products\": [\n \"<string>\"\n ],\n \"variants\": [\n {}\n ],\n \"collections\": [\n \"<string>\"\n ],\n \"conditions\": {}\n },\n \"discount\": {\n \"type\": \"<string>\",\n \"value\": 123\n }\n }\n ],\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 \"responseOptions\": {\n \"mediaPreloads\": {\n \"enabled\": true,\n \"srcsetSizes\": [\n 123\n ],\n \"sizes\": \"<string>\"\n }\n }\n}"
response = http.request(request)
puts response.read_bodyPOST /storefront/v1/search/product/7003338965178
{
"variant_id": 41234567890123,
"pagination": {
"page": 1,
"limit": 20
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"deviceId": "device-uuid"
}
}
{
"results": [
{
"id": 7003338965178,
"title": "SUPREME SEALLINE SEE POUCH SMALL",
"body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
"vendor": "SUPREME",
"product_type": "Accessories",
"created_at": "2022-02-05T01:22:05.000000Z",
"handle": "supreme-pouch-44370ss18a32-sm",
"updated_at": "2023-10-25T20:47:04.000000Z",
"published_at": "2022-02-05T01:22:05.000000Z",
"tags": [
"consignment",
],
"images": [
{
"alt": "SUPREME POUCH",
"src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
"width": 800,
"height": 534,
"variant_ids": []
}
],
"metafields": {
"product": {
"alias": "SEALLINE SEE POUCH SMALL",
"colorway": "BLACK",
"styleCode": "SS18A30 BLACK",
"yearOfRelease": 2018,
"searchColor": [
"black"
]
}
},
"available": true,
"price_range": {
"from": 30,
"to": 30
}
}
],
"totalResults": 1000,
"page": 1,
"totalPages": 20,
"facets": {
"vendor": {
"ADIDAS": 30,
"JORDAN": 336,
"NEW BALANCE": 15,
"NIKE": 384,
"REEBOK": 4,
"SUPREME": 624,
"VANS": 32
}
},
"attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}
Product Search
Search API: Similar Products
Similar Products API endpoint that returns visually and semantically related items to a given product from your catalog for recommendation carousels.
POST
/
search
/
product
/
{searchProductId}
Search API: Similar Products
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId} \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '
{
"variant_id": 123,
"attributes": [
"<string>"
],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": [
"<string>"
],
"retrieveFacetCount": true,
"includeFacetRanges": true,
"enrichFacetMetaobjects": true,
"sort_order_code": "<string>",
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"discountEntitlements": [
{
"entitled": {
"all": true,
"products": [
"<string>"
],
"variants": [
{}
],
"collections": [
"<string>"
],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"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": {}
},
"responseOptions": {
"mediaPreloads": {
"enabled": true,
"srcsetSizes": [
123
],
"sizes": "<string>"
}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId}"
payload = {
"variant_id": 123,
"attributes": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"enrichFacetMetaobjects": True,
"sort_order_code": "<string>",
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"discountEntitlements": [
{
"entitled": {
"all": True,
"products": ["<string>"],
"variants": [{}],
"collections": ["<string>"],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"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": {}
},
"responseOptions": { "mediaPreloads": {
"enabled": True,
"srcsetSizes": [123],
"sizes": "<string>"
} }
}
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({
variant_id: 123,
attributes: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
enrichFacetMetaobjects: true,
sort_order_code: '<string>',
defaultSelectedOptions: [{optionCode: '<string>', value: '<string>'}],
discountEntitlements: [
{
entitled: {
all: true,
products: ['<string>'],
variants: [{}],
collections: ['<string>'],
conditions: {}
},
discount: {type: '<string>', value: 123}
}
],
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: {}
},
responseOptions: {mediaPreloads: {enabled: true, srcsetSizes: [123], sizes: '<string>'}}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId}', 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/product/{searchProductId}",
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([
'variant_id' => 123,
'attributes' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'enrichFacetMetaobjects' => true,
'sort_order_code' => '<string>',
'defaultSelectedOptions' => [
[
'optionCode' => '<string>',
'value' => '<string>'
]
],
'discountEntitlements' => [
[
'entitled' => [
'all' => true,
'products' => [
'<string>'
],
'variants' => [
[
]
],
'collections' => [
'<string>'
],
'conditions' => [
]
],
'discount' => [
'type' => '<string>',
'value' => 123
]
]
],
'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' => [
]
],
'responseOptions' => [
'mediaPreloads' => [
'enabled' => true,
'srcsetSizes' => [
123
],
'sizes' => '<string>'
]
]
]),
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/product/{searchProductId}"
payload := strings.NewReader("{\n \"variant_id\": 123,\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 \"sort_order_code\": \"<string>\",\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"discountEntitlements\": [\n {\n \"entitled\": {\n \"all\": true,\n \"products\": [\n \"<string>\"\n ],\n \"variants\": [\n {}\n ],\n \"collections\": [\n \"<string>\"\n ],\n \"conditions\": {}\n },\n \"discount\": {\n \"type\": \"<string>\",\n \"value\": 123\n }\n }\n ],\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 \"responseOptions\": {\n \"mediaPreloads\": {\n \"enabled\": true,\n \"srcsetSizes\": [\n 123\n ],\n \"sizes\": \"<string>\"\n }\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/product/{searchProductId}")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"variant_id\": 123,\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 \"sort_order_code\": \"<string>\",\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"discountEntitlements\": [\n {\n \"entitled\": {\n \"all\": true,\n \"products\": [\n \"<string>\"\n ],\n \"variants\": [\n {}\n ],\n \"collections\": [\n \"<string>\"\n ],\n \"conditions\": {}\n },\n \"discount\": {\n \"type\": \"<string>\",\n \"value\": 123\n }\n }\n ],\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 \"responseOptions\": {\n \"mediaPreloads\": {\n \"enabled\": true,\n \"srcsetSizes\": [\n 123\n ],\n \"sizes\": \"<string>\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/search/product/{searchProductId}")
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 \"variant_id\": 123,\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 \"sort_order_code\": \"<string>\",\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"discountEntitlements\": [\n {\n \"entitled\": {\n \"all\": true,\n \"products\": [\n \"<string>\"\n ],\n \"variants\": [\n {}\n ],\n \"collections\": [\n \"<string>\"\n ],\n \"conditions\": {}\n },\n \"discount\": {\n \"type\": \"<string>\",\n \"value\": 123\n }\n }\n ],\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 \"responseOptions\": {\n \"mediaPreloads\": {\n \"enabled\": true,\n \"srcsetSizes\": [\n 123\n ],\n \"sizes\": \"<string>\"\n }\n }\n}"
response = http.request(request)
puts response.read_bodyPOST /storefront/v1/search/product/7003338965178
{
"variant_id": 41234567890123,
"pagination": {
"page": 1,
"limit": 20
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"deviceId": "device-uuid"
}
}
{
"results": [
{
"id": 7003338965178,
"title": "SUPREME SEALLINE SEE POUCH SMALL",
"body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
"vendor": "SUPREME",
"product_type": "Accessories",
"created_at": "2022-02-05T01:22:05.000000Z",
"handle": "supreme-pouch-44370ss18a32-sm",
"updated_at": "2023-10-25T20:47:04.000000Z",
"published_at": "2022-02-05T01:22:05.000000Z",
"tags": [
"consignment",
],
"images": [
{
"alt": "SUPREME POUCH",
"src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
"width": 800,
"height": 534,
"variant_ids": []
}
],
"metafields": {
"product": {
"alias": "SEALLINE SEE POUCH SMALL",
"colorway": "BLACK",
"styleCode": "SS18A30 BLACK",
"yearOfRelease": 2018,
"searchColor": [
"black"
]
}
},
"available": true,
"price_range": {
"from": 30,
"to": 30
}
}
],
"totalResults": 1000,
"page": 1,
"totalPages": 20,
"facets": {
"vendor": {
"ADIDAS": 30,
"JORDAN": 336,
"NEW BALANCE": 15,
"NIKE": 384,
"REEBOK": 4,
"SUPREME": 624,
"VANS": 32
}
},
"attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}
How results are served
Similar products results are precomputed and cached for fast response times. The system runs the full ranking pipeline — combining visual and semantic similarity with behavioral signals — and stores the top results for each product. When you call this endpoint, results are served from the precomputed cache. If no precomputed data exists for a product (for example, a newly added product), the system falls back to computing similarity in real time. Precomputed results are refreshed daily and incrementally when a product’s content changes. All request parameters (filters, facets, pagination, and sort orders) work the same regardless of whether results are served from cache or computed in real time. When you passvariant_id in the request body, results are always computed in real time from that variant. Shoppers viewing different variants of the same product see different recommendations.
Authorization
string
required
Token-based authentication header in the form of
<YOUR_LAYERS_TOKEN>.Headers
string
default:"application/json"
required
string
default:"application/json"
required
Path parameters
integer
required
The ID of the product for which you want to find similar products.
Body
integer
When provided, the endpoint seeds similarity from that variant rather than the product as a whole. Results then reflect the variant’s visual and semantic attributes, such as a specific color or material. Pass the variant currently selected on the product detail page.The value is only used when the variant belongs to the anchor product in the path. If it doesn’t match, the value is silently ignored and results fall back to product-level similarity. If the variant isn’t indexed yet, results also degrade to product-level similarity.When
variant_id is set, results are computed in real time rather than served from the precomputed cache. Different variants of the same product return different results and are cached under separate keys.string[]
Product attributes to include in the response. By default, all attributes are included. 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, first_or_matched_variant, and variants. See the Product Schema for detailed descriptions, including nested field selection for slicing arrays and filtering collections (for example, images[:2].src, variants[sku=ABC].price, metafields[namespace=custom]).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.string
Code of the sort order to apply. Use
"relevance" for the default relevance-based ranking, or any custom sort order code configured in your store. Retrieve available sort order codes from the Sort Orders API.array
Specify which product variants should be selected by default in the
Behavior:
first_or_matched_variant field.Show Properties
Show Properties
- Uses OR logic - selects the first variant matching ANY of the specified option values
- Falls back to the first variant by position if no match is found
- Automatically skipped when any option or variant filters are applied (filters take precedence)
- Only affects the
first_or_matched_variantfield in the response
array
Apply discounts to products, variants, or collections. When provided, price-based sorting and filtering will use discounted prices. See the Discount Entitlements guide for detailed usage.
Show Discount Entitlement Object
Show Discount Entitlement Object
object
required
Defines which products qualify for the discount.
Show entitled
Show entitled
boolean
When
true, applies discount to all products. When false, uses products, variants, or collections arrays.string[]
Array of product IDs or handles that qualify for the discount.
string[] | number[]
Array of variant IDs that qualify for the discount.
string[]
Array of collection handles that qualify for the discount.
object
Optional filter group that qualifies products for the discount based on their attributes (for example,
tags or vendor). Uses the same shape as the top-level filter_group parameter. Matches are additive with products, variants, and collections on the same entitlement.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.
object
Per-request overrides for response behavior. Currently controls image preload hints emitted in the
Example:
Link response header. You can disable preloads or narrow the srcset to the breakpoints your storefront uses. You cannot enable preloads when the store has them disabled.Show Properties
Show Properties
object
Controls the
Link: rel=\"preload\" directives generated for product images in this response. See Early hints for background.Show Properties
Show Properties
boolean
default:"true"
Set to
false to skip the Link header for this request. Useful for server-rendered pages that do not benefit from preload hints, or when you want to reduce response header size. Cannot enable preloads if they are disabled at the store level.int[]
Custom responsive image widths (in pixels) to emit in
imagesrcset. Each value must be an integer between 1 and 10000. Overrides the store-level srcset configuration for this request only. When omitted, the store configuration or platform defaults are used.string
Media query string emitted as the
imagesizes attribute in the preload Link header (for example (max-width: 600px) 100vw, 50vw). Tells the browser which srcset width to pick per viewport. Overrides the store-level sizes value for this request only. When omitted or empty, the store configuration is used.{
"responseOptions": {
"mediaPreloads": {
"enabled": true,
"srcsetSizes": [320, 640, 960],
"sizes": "(max-width: 600px) 100vw, 50vw"
}
}
}
Response
Array of Objects
Show Properties
Show Properties
number
The unique identifier of the product.
string
The title of the product.
string
The HTML content describing the product.
string
The vendor of the product.
string
The type of the product.
number
The timestamp when the product was created.
string
The handle of the product.
number
The timestamp when the product was updated.
number
The timestamp when the product was published.
Array of strings
The tags associated with the product.
number
The parent product id if a child in a Combined Listing.
string
The role of the product if part of a Combined Listing.
Array of Objects
Object
The metafields of the product.
Object
The computed attributes of the product. Only includes attributes with non-null, non-empty values. Attributes that evaluate to null or an empty string are omitted.
Object
Object
The first available variant (depending on OOS settings) or the variant matched with a filter or search query.
Show Properties
Show Properties
number
The ID of the variant.
string
The title of the variant.
boolean
The availability of the variant.
number
The sku of the variant.
string
The price of the variant.
string
The compare at price of the variant.
Object
The metafields of the variant.
Array of Objects
number
The position of the variant in the product’s variant list.
number
Total inventory quantity across all locations. Only included when the store has the Expose Variant Inventory setting enabled.
string
Inventory policy for the variant:
DENY (stop selling when out of stock) or CONTINUE (allow overselling). Only included when the store has the Expose Variant Inventory setting enabled.object
Object mapping location IDs to available inventory quantities (e.g.,
{"1001": 5, "1002": 10}). Returns empty object {} when no inventory data exists. Only included when the store has the Expose Variant Inventory setting enabled.Object
boolean
The availability of the product.
number
The total number of results.
number
The current page number.
number
The total number of pages.
object
If
includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.object
If
retrieveFacetCount is true then an object with keys and values of the specified attributes. Empty values and literal "null" strings are automatically excluded from facet results.object
Only returned when
enrichFacetMetaobjects is true and at least one requested facet is backed by a metaobject_reference or list.metaobject_reference metafield. Keys are facet attribute codes and values map each facet value (the referenced metaobject’s handle) to the metaobject’s display_name and fields. Handles with no matching cached metaobject are omitted here and remain as plain values in facets. See Metaobjects and reference metafields for the normalized field shape.string
A unique request identifier (ULID) for this API call. Use this token to correlate requests with analytics events via the Beacon API.
object
Show Properties
Show Properties
array of objects
Array of variant breakout configurations applied to search. Only present when one or more variant breakouts are active for search requests. Multiple breakouts with different option codes can work simultaneously.
Show Properties
Show Properties
string
The unique identifier of the variant breakout configuration.
string
The display name of the variant breakout configuration (e.g., “Gemstone Breakout”, “Color Breakout”).
string
The product option code that determines which variants are broken out (e.g., “Stone”, “Color”). Each product is broken out by the first matching option code from the array.
object
Echoes the image preload configuration used to build the
Link response header for this request. Only present when image preloads are emitted. See Early hints.Show Properties
Show Properties
int[]
The responsive image widths (in pixels) used in the
imagesrcset of the Link header. Reflects the request override when provided, otherwise the store-level configuration or platform defaults.array of objects
An ordered trace of processing steps the engine performed. See the Text Search documentation for the full list of possible step types.
Response headers
| Header | Description |
|---|---|
x-request-id | A unique identifier (ULID) for the request. This matches the attributionToken in the response body. |
x-layers-build | The Layers build version that served the request. |
X-Layers-Results-Cache | Indicates whether the response was served from the results cache. Returns HIT or MISS. |
Link | Contains rel="preload" directives for product images (up to 6 items). See Early hints for details. Only included when early hints are enabled (enabled by default). |
POST /storefront/v1/search/product/7003338965178
{
"variant_id": 41234567890123,
"pagination": {
"page": 1,
"limit": 20
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"deviceId": "device-uuid"
}
}
{
"results": [
{
"id": 7003338965178,
"title": "SUPREME SEALLINE SEE POUCH SMALL",
"body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
"vendor": "SUPREME",
"product_type": "Accessories",
"created_at": "2022-02-05T01:22:05.000000Z",
"handle": "supreme-pouch-44370ss18a32-sm",
"updated_at": "2023-10-25T20:47:04.000000Z",
"published_at": "2022-02-05T01:22:05.000000Z",
"tags": [
"consignment",
],
"images": [
{
"alt": "SUPREME POUCH",
"src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
"width": 800,
"height": 534,
"variant_ids": []
}
],
"metafields": {
"product": {
"alias": "SEALLINE SEE POUCH SMALL",
"colorway": "BLACK",
"styleCode": "SS18A30 BLACK",
"yearOfRelease": 2018,
"searchColor": [
"black"
]
}
},
"available": true,
"price_range": {
"from": 30,
"to": 30
}
}
],
"totalResults": 1000,
"page": 1,
"totalPages": 20,
"facets": {
"vendor": {
"ADIDAS": 30,
"JORDAN": 336,
"NEW BALANCE": 15,
"NIKE": 384,
"REEBOK": 4,
"SUPREME": 624,
"VANS": 32
}
},
"attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}
Was this page helpful?
⌘I