Browse API: Browse Collection Page
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/browse/{collection_handle} \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '
{
"sort_order_code": "<string>",
"dynamicLinking": {
"products": [
{}
]
},
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"attributes": [
"<string>"
],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": [
"<string>"
],
"retrieveFacetCount": true,
"includeFacetRanges": true,
"discountEntitlements": [
{
"entitled": {
"all": true,
"products": [
"<string>"
],
"variants": [
{}
],
"collections": [
"<string>"
],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"identity": {
"deviceId": "<string>",
"sessionId": "<string>",
"customerId": "<string>",
"companyLocationId": "<string>"
},
"preview_id": "<string>",
"forceHideOutOfStock": true,
"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
]
}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/browse/{collection_handle}"
payload = {
"sort_order_code": "<string>",
"dynamicLinking": { "products": [{}] },
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"attributes": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"discountEntitlements": [
{
"entitled": {
"all": True,
"products": ["<string>"],
"variants": [{}],
"collections": ["<string>"],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"identity": {
"deviceId": "<string>",
"sessionId": "<string>",
"customerId": "<string>",
"companyLocationId": "<string>"
},
"preview_id": "<string>",
"forceHideOutOfStock": True,
"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]
} }
}
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({
sort_order_code: '<string>',
dynamicLinking: {products: [{}]},
defaultSelectedOptions: [{optionCode: '<string>', value: '<string>'}],
attributes: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
discountEntitlements: [
{
entitled: {
all: true,
products: ['<string>'],
variants: [{}],
collections: ['<string>'],
conditions: {}
},
discount: {type: '<string>', value: 123}
}
],
identity: {
deviceId: '<string>',
sessionId: '<string>',
customerId: '<string>',
companyLocationId: '<string>'
},
preview_id: '<string>',
forceHideOutOfStock: true,
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]}}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/browse/{collection_handle}', 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/browse/{collection_handle}",
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([
'sort_order_code' => '<string>',
'dynamicLinking' => [
'products' => [
[
]
]
],
'defaultSelectedOptions' => [
[
'optionCode' => '<string>',
'value' => '<string>'
]
],
'attributes' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'discountEntitlements' => [
[
'entitled' => [
'all' => true,
'products' => [
'<string>'
],
'variants' => [
[
]
],
'collections' => [
'<string>'
],
'conditions' => [
]
],
'discount' => [
'type' => '<string>',
'value' => 123
]
]
],
'identity' => [
'deviceId' => '<string>',
'sessionId' => '<string>',
'customerId' => '<string>',
'companyLocationId' => '<string>'
],
'preview_id' => '<string>',
'forceHideOutOfStock' => true,
'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
]
]
]
]),
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/browse/{collection_handle}"
payload := strings.NewReader("{\n \"sort_order_code\": \"<string>\",\n \"dynamicLinking\": {\n \"products\": [\n {}\n ]\n },\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\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 \"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 \"preview_id\": \"<string>\",\n \"forceHideOutOfStock\": true,\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 }\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/browse/{collection_handle}")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"sort_order_code\": \"<string>\",\n \"dynamicLinking\": {\n \"products\": [\n {}\n ]\n },\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\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 \"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 \"preview_id\": \"<string>\",\n \"forceHideOutOfStock\": true,\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 }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/browse/{collection_handle}")
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 \"sort_order_code\": \"<string>\",\n \"dynamicLinking\": {\n \"products\": [\n {}\n ]\n },\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\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 \"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 \"preview_id\": \"<string>\",\n \"forceHideOutOfStock\": true,\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 }\n }\n}"
response = http.request(request)
puts response.read_bodyPOST /storefront/v1/browse/summer-collection
{
"sort_order_code": "best-sellers",
"pagination": {
"page": 1,
"limit": 20
},
"retrieveFacetCount": true,
"facets": ["vendor", "product_type"],
"context": {
"geo": {
"country": "US",
"province": "California"
},
"marketing": {
"source": "google",
"medium": "cpc",
"campaign": "summer-sale"
},
"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": "01JRVX8M3N4P5Q6R7S8T9U0V1W",
"_meta": {
"appliedRules": [],
"appliedSearchRules": [],
"affinities": [
{
"property": "vendor",
"operator": "=",
"value": "SUPREME",
"weight": 0.74
}
]
},
"_workflow": [
{
"type": "affinity-boosts",
"payload": [
{
"property": "vendor",
"operator": "eq",
"value": "SUPREME",
"weight": 0.74
}
]
}
]
}
Browse
Browse API: Browse Collection Page
Browse API endpoint to fetch, filter, sort, and paginate merchandised collection pages in your catalog with facets, pins, and personalization applied.
POST
/
browse
/
{collection_handle}
Browse API: Browse Collection Page
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/browse/{collection_handle} \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '
{
"sort_order_code": "<string>",
"dynamicLinking": {
"products": [
{}
]
},
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"attributes": [
"<string>"
],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": [
"<string>"
],
"retrieveFacetCount": true,
"includeFacetRanges": true,
"discountEntitlements": [
{
"entitled": {
"all": true,
"products": [
"<string>"
],
"variants": [
{}
],
"collections": [
"<string>"
],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"identity": {
"deviceId": "<string>",
"sessionId": "<string>",
"customerId": "<string>",
"companyLocationId": "<string>"
},
"preview_id": "<string>",
"forceHideOutOfStock": true,
"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
]
}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/browse/{collection_handle}"
payload = {
"sort_order_code": "<string>",
"dynamicLinking": { "products": [{}] },
"defaultSelectedOptions": [
{
"optionCode": "<string>",
"value": "<string>"
}
],
"attributes": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"discountEntitlements": [
{
"entitled": {
"all": True,
"products": ["<string>"],
"variants": [{}],
"collections": ["<string>"],
"conditions": {}
},
"discount": {
"type": "<string>",
"value": 123
}
}
],
"identity": {
"deviceId": "<string>",
"sessionId": "<string>",
"customerId": "<string>",
"companyLocationId": "<string>"
},
"preview_id": "<string>",
"forceHideOutOfStock": True,
"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]
} }
}
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({
sort_order_code: '<string>',
dynamicLinking: {products: [{}]},
defaultSelectedOptions: [{optionCode: '<string>', value: '<string>'}],
attributes: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
discountEntitlements: [
{
entitled: {
all: true,
products: ['<string>'],
variants: [{}],
collections: ['<string>'],
conditions: {}
},
discount: {type: '<string>', value: 123}
}
],
identity: {
deviceId: '<string>',
sessionId: '<string>',
customerId: '<string>',
companyLocationId: '<string>'
},
preview_id: '<string>',
forceHideOutOfStock: true,
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]}}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/browse/{collection_handle}', 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/browse/{collection_handle}",
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([
'sort_order_code' => '<string>',
'dynamicLinking' => [
'products' => [
[
]
]
],
'defaultSelectedOptions' => [
[
'optionCode' => '<string>',
'value' => '<string>'
]
],
'attributes' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'discountEntitlements' => [
[
'entitled' => [
'all' => true,
'products' => [
'<string>'
],
'variants' => [
[
]
],
'collections' => [
'<string>'
],
'conditions' => [
]
],
'discount' => [
'type' => '<string>',
'value' => 123
]
]
],
'identity' => [
'deviceId' => '<string>',
'sessionId' => '<string>',
'customerId' => '<string>',
'companyLocationId' => '<string>'
],
'preview_id' => '<string>',
'forceHideOutOfStock' => true,
'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
]
]
]
]),
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/browse/{collection_handle}"
payload := strings.NewReader("{\n \"sort_order_code\": \"<string>\",\n \"dynamicLinking\": {\n \"products\": [\n {}\n ]\n },\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\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 \"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 \"preview_id\": \"<string>\",\n \"forceHideOutOfStock\": true,\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 }\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/browse/{collection_handle}")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"sort_order_code\": \"<string>\",\n \"dynamicLinking\": {\n \"products\": [\n {}\n ]\n },\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\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 \"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 \"preview_id\": \"<string>\",\n \"forceHideOutOfStock\": true,\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 }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/browse/{collection_handle}")
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 \"sort_order_code\": \"<string>\",\n \"dynamicLinking\": {\n \"products\": [\n {}\n ]\n },\n \"defaultSelectedOptions\": [\n {\n \"optionCode\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\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 \"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 \"preview_id\": \"<string>\",\n \"forceHideOutOfStock\": true,\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 }\n }\n}"
response = http.request(request)
puts response.read_bodyPOST /storefront/v1/browse/summer-collection
{
"sort_order_code": "best-sellers",
"pagination": {
"page": 1,
"limit": 20
},
"retrieveFacetCount": true,
"facets": ["vendor", "product_type"],
"context": {
"geo": {
"country": "US",
"province": "California"
},
"marketing": {
"source": "google",
"medium": "cpc",
"campaign": "summer-sale"
},
"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": "01JRVX8M3N4P5Q6R7S8T9U0V1W",
"_meta": {
"appliedRules": [],
"appliedSearchRules": [],
"affinities": [
{
"property": "vendor",
"operator": "=",
"value": "SUPREME",
"weight": 0.74
}
]
},
"_workflow": [
{
"type": "affinity-boosts",
"payload": [
{
"property": "vendor",
"operator": "eq",
"value": "SUPREME",
"weight": 0.74
}
]
}
]
}
Authorization
Token-based authentication header in the form of
<YOUR_LAYERS_TOKEN>.Headers
Path parameters
The handle of the collection you wish to browse.
Body
Code of the sort order. If omitted, the collection’s default sort order will be used (configured via the Layers dashboard or the
layers.default_sort_order metafield on the collection).Dynamic Linking allows you to promote specific products to the top of the first page of results. This feature takes priority over merchandising rules and sort orders.
If the Layers tracking pixel is installed, this parameter is automatically injected when customers arrive with a
utm_products URL parameter (e.g., ?utm_products=summer-dress-blue_classic-tee-white_beach-hat). See Dynamic Linking for ads for details.Show Properties
Show Properties
Array of product identifiers (handles or IDs) in the order you want them to appear. The first item will be position 1, second item position 2, etc.
- Handles: String values (e.g.,
"summer-dress-blue") - IDs: Numeric values (e.g.,
8234567890123) - Mixed: You can combine both handles and IDs in the same array
- Only applies on the first page of results (page 1)
- Non-existent or unavailable products are silently skipped
- Subsequent products shift up to fill any gaps
- Takes priority over merchandising rules and sort orders
{
"dynamicLinking": {
"products": ["summer-dress-blue", 8234567890123, "classic-tee-white"]
}
}
Specify which product variants should be selected by default in the
Behavior:Multiple options example (OR logic):This will select variants with either February OR March birthstone, preferring the first match found.
first_or_matched_variant field. This is useful for scenarios like defaulting to a specific birthstone option in a jewelry collection.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 - Works with Variant Breakouts - product tiles respect your default selected options, and variant tiles respect non-breakout default selected options (preferring variants that match your preferences within each breakout group, with fallback to position ordering)
{
"defaultSelectedOptions": [
{
"optionCode": "birthstone",
"value": "February"
}
]
}
{
"defaultSelectedOptions": [
{
"optionCode": "birthstone",
"value": "February"
},
{
"optionCode": "birthstone",
"value": "March"
}
]
}
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]).Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
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.*"]
If the count of each facet value should be calculated
If you want a min/max range for numeric facets such as price.
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
Defines which products qualify for the discount.
Show entitled
Show entitled
When
true, applies discount to all products. When false, uses products, variants, or collections arrays.Array of product IDs or handles that qualify for the discount.
Array of variant IDs that qualify for the discount.
Array of collection handles that qualify for the discount.
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.User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
Show Properties
Show Properties
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.
Temporary session identifier. Typically corresponds to the Shopify session ID and expires after inactivity or when the browser is closed.
Shopify customer ID for authenticated users. Only present when the user is signed in to their account.
Shopify B2B company location GID (e.g.
gid://shopify/CompanyLocation/123456789) for the authenticated buyer. Layers resolves the catalog assigned to the company location and uses it to scope results: only products in the catalog are returned, prices come from the catalog’s price list, and excluded collections return 404. Omit for retail (DTC) traffic. See B2B catalogs.When provided, the Browse API loads the specified preview rule instead of the collection’s active merchandising rule. Preview rules are temporary and expire one hour after creation.This parameter is automatically included when you open a preview URL from the Layers dashboard. You do not need to set it manually in production integrations.Behavior:
- Overrides normal merchandising rule resolution for this request
- Analytics and beacon events are not recorded for preview requests
- Returns a
404if the preview has expired or does not exist
When set to
true, products with no available variants are excluded from results regardless of the store-level out-of-stock visibility setting. If your store has location-based stock checking configured, the same location rules apply.This is useful when a specific browse integration or page requires strict in-stock filtering even though the store default allows out-of-stock products to appear.Store-level out-of-stock demoting (the “At the end” option) does not apply to browse results. Browse relies on the Shopify collection itself for product ordering. When you set
forceHideOutOfStock to true on a browse request, out-of-stock products are hidden entirely rather than demoted.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
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.
Products currently in the customer’s cart. Used to surface complementary products and influence relevance scoring.
Show Array Item Properties
Show Array Item Properties
Product title.
Product price.
Product type or category.
Product identifier. Accepts a numeric ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").Product variant identifier.
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.
Show Array Item Properties
Show Array Item Properties
Product title.
Product price at time of purchase.
Product type or category.
Product identifier. Accepts a numeric ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").Product variant identifier.
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).Recent search queries and their outcomes. Helps understand customer intent and refine relevance models.
Show Array Item Properties
Show Array Item Properties
Aggregated customer behavior and purchase patterns for personalization.
Show Properties
Show Properties
Whether the customer is currently authenticated.
Whether this is a returning customer.
Total number of orders placed.
Average order value in store currency.
Average days between orders.
Days since the most recent order.
Days since the first order.
Total amount spent in store currency.
Explicitly set the Shopify Market for this request. Used for market-specific product availability filtering and contextual pricing. Accepts a two-letter country code (e.g.,
"US", "CA"), a numeric Shopify Market ID (e.g., "12345"), or a Shopify Market GID (e.g., "gid://shopify/Market/12345").When not provided, the market is automatically resolved from the geo.country field (or the shopper’s detected country for client-side requests). If no matching market is found, the store’s primary market is used as the fallback.Behavior depends on the store’s market application mode:- Strict — Products are filtered to only those available in the resolved market, and market-specific pricing is applied
- Pricing only — The full catalog remains visible, but variant prices are swapped to market-specific values where available
- Off — Market resolution is skipped entirely; base catalog and base pricing are used for all shoppers
The shopping channel the customer is browsing from. Used for channel-specific merchandising, sorting, and analytics segmentation. Automatically detected from request headers when not provided (e.g., mobile app requests via Tapcart or Canvas are detected as
"app").Accepted values:"web"— Standard web browser (default)"app"— Mobile app (e.g., Tapcart, Canvas)
Custom contextual data specific to your implementation. Structure is flexible and can contain any key-value pairs relevant to your use case.
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
Controls the
Link: rel=\"preload\" directives generated for product images in this response. See Early hints for background.Show Properties
Show Properties
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.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.{
"responseOptions": {
"mediaPreloads": {
"enabled": true,
"srcsetSizes": [320, 640, 960]
}
}
}
Response
Show Properties
Show Properties
The unique identifier of the product.
The title of the product.
The HTML content describing the product.
The vendor of the product.
The type of the product.
The timestamp when the product was created.
The handle of the product.
The timestamp when the product was updated.
The timestamp when the product was published.
The tags associated with the product.
The parent product id if a child in a Combined Listing.
The role of the product if part of a Combined Listing.
The metafields of the product.
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.
The first available variant (depending on OOS settings) or the variant matched with a filter or search query.
Show Properties
Show Properties
The ID of the variant.
The title of the variant.
The availability of the variant.
The sku of the variant.
The price of the variant.
The compare at price of the variant.
The metafields of the variant.
The position of the variant in the product’s variant list.
Total inventory quantity across all locations. Only included when the store has the Expose Variant Inventory setting enabled.
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 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.The availability of the product.
The total number of results. When variant breakouts are enabled, this reflects the count of tiles (both product and variant tiles) rather than just products.The count is scoped to the visibility of the active shopping channel. When
context.shoppingChannel is "web" (the default), only products published to the online store are counted. When it is "app" and an app sales channel is configured, only products published to that channel are counted. As a result, totalResults always matches the number of products a shopper can actually see for that channel.The current page number.
The total number of pages. Calculated based on tile count when variant breakouts are enabled.
If
retrieveFacetCount is true then an object with keys and values of the specified attributes. When variant breakouts are enabled, facet counts reflect tile counts rather than product counts. Empty values and literal "null" strings are automatically excluded from facet results.Counts are scoped to the visibility of the active shopping channel, so they match the number of products (or tiles) a shopper can actually see. Products that are not published to the requester’s channel, are B2B-only, or are hidden by a combined-listing role are excluded from every bucket. When context.shoppingChannel is "app" but the store does not have an app sales channel configured, counts fall back to the web channel.When filter_group is present, counts follow the standard “OR within a facet, AND across facets” pattern. Facets whose condition uses a multi-select operator (IN, NOT IN) are counted against every other active filter except the facet’s own, so other values in the same facet stay selectable. Facets whose condition uses a single-select or predicate operator (EQ, NEQ, GT, LT, BETWEEN, NULL, and so on) are counted against the fully filtered result set.If
includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.Merchandising banners emitted by any merchandising rules that matched this request. Flat across all applied rules and pre-sorted by
sort_index. Your storefront is responsible for rendering banners into the grid — see Rendering banners in Liquid and Rendering banners with the SDK. The IDs of the rules that produced these banners are available on _meta.appliedRules.Show Properties
Show Properties
Banner ULID.
Internal name (not shown to shoppers).
"inject" or "overtake". inject inserts the banner at position and shifts trailing products; overtake replaces the product at position.Click-through URL. Only honored on
inject banners.Application order when a rule has multiple banners. Lower wins on conflicting cells.
Desktop media.
{ id, src, alt, width, height, source, mediaContentType }. source is "store_file" today and mediaContentType is "IMAGE" today.Mobile media. Same shape as
web_media.Desktop layout.
{ placement: "hero" | "inline", width, height, position }. For hero, render above the grid regardless of position. For inline, position is a row-major 0-indexed grid cell.Mobile layout. Same shape as
web_layout.A unique request identifier (ULID) for this API call. Use this token to correlate browse requests with analytics events via the Beacon API, and to match requests to entries in the Search Inspector.
Show Properties
Show Properties
The merchandising rule ID’s applied to the request.
The IDs of request transforms that matched and were applied to this request. Returns an empty array when no request transforms matched. Use this to verify which request transforms are affecting a given browse request.
User affinity signals derived from the session’s contextual information. Only present when you pass the
context and identity parameters and the engine detects meaningful affinity patterns from cart contents and purchase history. The array contains both promotion entries (positive weights for preferred attribute values) and demotion entries (small negative weights for non-preferred values within the same attribute). Entries are grouped by property and sorted by weight in descending order.Show Properties
Show Properties
The product attribute the affinity applies to (e.g.,
"vendor", "product_type", "named_tags.color", "options.Size").The comparison operator.
"eq" for promotion entries that boost a specific value. "not_in" for demotion entries that slightly suppress products that don’t match any detected preference for this attribute.For promotion entries (
"eq"): the specific attribute value that was boosted (e.g., "Nike", "Running Shoes"). For demotion entries ("not_in"): an array of all promoted values for this attribute, so products not matching any of them receive a small negative boost.The boost weight applied. Promotion weights range from
0 to 1.2, where higher values indicate stronger preferences. Demotion weights are small negative values proportional to the strongest promotion in the same attribute group. Option-level attributes (e.g., options.Size) receive lower weights than product-level attributes (e.g., vendor).Array of variant breakout configurations applied to this collection. Only present when one or more variant breakouts are active for the collection. Multiple breakouts with different option codes can work simultaneously in the same collection. Each object has the structure
{optionCode: "Stone"}.Show Properties
Show Properties
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.
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
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.Echoes the discount entitlements applied to this request. Only present when the request included
discountEntitlements (either directly or via a matched request transform). Use this to render discount badges or labels on the storefront without re-deriving which entitlements matched. Each entry mirrors the entitlement shape sent in the request.Show Properties
Show Properties
The entitlement criteria that qualified products for the discount. Contains any of
all, products, variants, collections, or conditions. See the entitlement criteria reference.An ordered trace of processing steps the engine performed to produce results for this request. Each entry represents a stage in the browse pipeline, recorded in the order it was executed. Use this field to understand which merchandising rules, sort orders, and boosts were applied.This field is useful for debugging browse behavior in development and is also surfaced in the Search Inspector panel.
Show Properties
Show Properties
The processing step type. Possible values include:
"rule-applied"— A merchandising rule was applied. Thepayloadcontains the rule identifier."affinity-boosts"— User affinity signals from session context were applied to personalize results."ranking-rules"— Ranking rules influenced result ordering.
The data associated with this processing step. The structure varies by
type.Response headers
Every API response includes the following headers for request tracing and performance optimization:| Header | Description |
|---|---|
x-request-id | A unique identifier (ULID) for the request. This matches the attributionToken in the response body. Use it to correlate requests across your infrastructure or when contacting support. |
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 when cached results were used, or MISS when results were computed fresh. |
Link | Contains rel="preload" directives for product images in the response (up to 6 items), enabling browsers and CDNs to begin fetching images before your application processes the JSON body. See Early hints for configuration options. Only included when early hints are enabled (enabled by default). |
Variant breakouts
When variant breakouts are configured, results may include both product tiles and variant tiles. Each result includes a__typename field to identify the tile type:
Identifies the type of tile in the results:
"Product"- A standard product tile"Variant"- An individual variant tile from a product with a configured breakout option
Variant tile fields
Variant tiles include additional fields to identify the specific variant:The parent product ID. Use this to link back to the full product or group variants from the same product.
The specific variant ID. For variant tiles, this matches the
id field.For variant tiles, the
id field contains the variant ID (not the product ID). The title field is formatted as "{product title} - {option value}" by default (e.g., “Amethyst Ring - Rose Quartz”), but this can be configured per breakout. If the breakout’s “Include Option Value in Title” setting is disabled, the title will be the original product title. See the Variant Breakouts documentation for more details.POST /storefront/v1/browse/summer-collection
{
"sort_order_code": "best-sellers",
"pagination": {
"page": 1,
"limit": 20
},
"retrieveFacetCount": true,
"facets": ["vendor", "product_type"],
"context": {
"geo": {
"country": "US",
"province": "California"
},
"marketing": {
"source": "google",
"medium": "cpc",
"campaign": "summer-sale"
},
"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": "01JRVX8M3N4P5Q6R7S8T9U0V1W",
"_meta": {
"appliedRules": [],
"appliedSearchRules": [],
"affinities": [
{
"property": "vendor",
"operator": "=",
"value": "SUPREME",
"weight": 0.74
}
]
},
"_workflow": [
{
"type": "affinity-boosts",
"payload": [
{
"property": "vendor",
"operator": "eq",
"value": "SUPREME",
"weight": 0.74
}
]
}
]
}
Was this page helpful?
⌘I