Blocks API: Get Block Products
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '
{
"anchor_id": "<string>",
"anchor_handle": "<string>",
"variant_id": 123,
"attributes": [
"<string>"
],
"excludeProductIds": [
"<string>"
],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": [
"<string>"
],
"retrieveFacetCount": true,
"includeFacetRanges": true,
"enrichFacetMetaobjects": 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>"
},
"context": {
"geo": {
"country": "<string>",
"province": "<string>",
"city": "<string>"
},
"productsInCart": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<string>",
"variantId": "<string>",
"options": {}
}
],
"productsPurchased": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {}
}
],
"priorSearches": [
{
"searchQuery": "<string>",
"hadClick": true,
"hasResults": true,
"fromPage": "<string>"
}
],
"marketing": {
"source": "<string>",
"medium": "<string>",
"campaign": "<string>",
"term": "<string>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": true,
"returning": true,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [
{}
],
"segments": [
{}
]
},
"market": "<string>",
"session": {
"returning": true
},
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
},
"responseOptions": {
"mediaPreloads": {
"enabled": true,
"srcsetSizes": [
123
],
"sizes": "<string>"
}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products"
payload = {
"anchor_id": "<string>",
"anchor_handle": "<string>",
"variant_id": 123,
"attributes": ["<string>"],
"excludeProductIds": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"enrichFacetMetaobjects": 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>"
},
"context": {
"geo": {
"country": "<string>",
"province": "<string>",
"city": "<string>"
},
"productsInCart": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<string>",
"variantId": "<string>",
"options": {}
}
],
"productsPurchased": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {}
}
],
"priorSearches": [
{
"searchQuery": "<string>",
"hadClick": True,
"hasResults": True,
"fromPage": "<string>"
}
],
"marketing": {
"source": "<string>",
"medium": "<string>",
"campaign": "<string>",
"term": "<string>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": True,
"returning": True,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [{}],
"segments": [{}]
},
"market": "<string>",
"session": { "returning": True },
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
},
"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({
anchor_id: '<string>',
anchor_handle: '<string>',
variant_id: 123,
attributes: ['<string>'],
excludeProductIds: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
enrichFacetMetaobjects: 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>'
},
context: {
geo: {country: '<string>', province: '<string>', city: '<string>'},
productsInCart: [
{
title: '<string>',
price: 123,
type: '<string>',
productId: '<string>',
variantId: '<string>',
options: {},
quantity: 123
}
],
freeShippingThreshold: 123,
productsViewed: [
{
id: '<string>',
at: 123,
title: '<string>',
type: '<string>',
variantId: '<string>',
options: {}
}
],
productsPurchased: [
{
title: '<string>',
price: 123,
type: '<string>',
productId: '<string>',
variantId: '<string>',
options: {}
}
],
priorSearches: [
{
searchQuery: '<string>',
hadClick: true,
hasResults: true,
fromPage: '<string>'
}
],
marketing: {
source: '<string>',
medium: '<string>',
campaign: '<string>',
term: '<string>',
content: '<string>',
clickIds: {},
referrer: '<string>',
landingPath: '<string>',
channel: '<string>'
},
experiments: {},
customer: {
signedIn: true,
returning: true,
numberOfOrders: 123,
averageOrderValue: 123,
daysBetweenOrders: 123,
daysSinceLastOrder: 123,
daysSinceOldestOrder: 123,
totalSpent: 123,
tags: [{}],
segments: [{}]
},
market: '<string>',
session: {returning: true},
locale: '<string>',
currency: '<string>',
b2bCompany: '<string>',
shoppingChannel: '<string>',
custom: {}
},
responseOptions: {mediaPreloads: {enabled: true, srcsetSizes: [123], sizes: '<string>'}}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products', 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/blocks/{blockId}/products",
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([
'anchor_id' => '<string>',
'anchor_handle' => '<string>',
'variant_id' => 123,
'attributes' => [
'<string>'
],
'excludeProductIds' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'enrichFacetMetaobjects' => 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>'
],
'context' => [
'geo' => [
'country' => '<string>',
'province' => '<string>',
'city' => '<string>'
],
'productsInCart' => [
[
'title' => '<string>',
'price' => 123,
'type' => '<string>',
'productId' => '<string>',
'variantId' => '<string>',
'options' => [
],
'quantity' => 123
]
],
'freeShippingThreshold' => 123,
'productsViewed' => [
[
'id' => '<string>',
'at' => 123,
'title' => '<string>',
'type' => '<string>',
'variantId' => '<string>',
'options' => [
]
]
],
'productsPurchased' => [
[
'title' => '<string>',
'price' => 123,
'type' => '<string>',
'productId' => '<string>',
'variantId' => '<string>',
'options' => [
]
]
],
'priorSearches' => [
[
'searchQuery' => '<string>',
'hadClick' => true,
'hasResults' => true,
'fromPage' => '<string>'
]
],
'marketing' => [
'source' => '<string>',
'medium' => '<string>',
'campaign' => '<string>',
'term' => '<string>',
'content' => '<string>',
'clickIds' => [
],
'referrer' => '<string>',
'landingPath' => '<string>',
'channel' => '<string>'
],
'experiments' => [
],
'customer' => [
'signedIn' => true,
'returning' => true,
'numberOfOrders' => 123,
'averageOrderValue' => 123,
'daysBetweenOrders' => 123,
'daysSinceLastOrder' => 123,
'daysSinceOldestOrder' => 123,
'totalSpent' => 123,
'tags' => [
[
]
],
'segments' => [
[
]
]
],
'market' => '<string>',
'session' => [
'returning' => true
],
'locale' => '<string>',
'currency' => '<string>',
'b2bCompany' => '<string>',
'shoppingChannel' => '<string>',
'custom' => [
]
],
'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/blocks/{blockId}/products"
payload := strings.NewReader("{\n \"anchor_id\": \"<string>\",\n \"anchor_handle\": \"<string>\",\n \"variant_id\": 123,\n \"attributes\": [\n \"<string>\"\n ],\n \"excludeProductIds\": [\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 \"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 \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n },\n \"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/blocks/{blockId}/products")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"anchor_id\": \"<string>\",\n \"anchor_handle\": \"<string>\",\n \"variant_id\": 123,\n \"attributes\": [\n \"<string>\"\n ],\n \"excludeProductIds\": [\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 \"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 \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n },\n \"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/blocks/{blockId}/products")
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 \"anchor_id\": \"<string>\",\n \"anchor_handle\": \"<string>\",\n \"variant_id\": 123,\n \"attributes\": [\n \"<string>\"\n ],\n \"excludeProductIds\": [\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 \"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 \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n },\n \"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/blocks/01HQXYZ123ABC456DEF789/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US",
"province": "California"
},
"productsInCart": [
{
"title": "Nike Air Force 1",
"productId": "8234567890123",
"variantId": "45678901234567"
}
],
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"deviceId": "device-uuid"
}
}
POST /storefront/v1/blocks/01HQXYZ654STU321VWX098/products
{
"anchor_id": "gid://shopify/Article/556677889900",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ789GHI012JKL345/products
{
"anchor_id": "summer-collection",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ789GHI012JKL345/products
{
"anchor_id": "summer-collection",
"pagination": {
"page": 1,
"limit": 20
},
"filter_group": {
"conditional": "AND",
"expressions": [
{
"property": "available",
"operator": "=",
"values": [true]
}
]
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
}
}
POST /storefront/v1/blocks/01HQXYZ456MNO789PQR012/products
{
"pagination": {
"page": 1,
"limit": 8
},
"context": {
"geo": {
"country": "US"
},
"productsInCart": [
{
"title": "Nike Air Force 1",
"productId": "8234567890123",
"variantId": "45678901234567"
},
{
"title": "Classic Tee",
"productId": "8234567890456",
"variantId": "45678901234890"
}
],
"shoppingChannel": "app"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"market": "CA",
"geo": {
"country": "CA"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"customerId": "8123456789",
"companyLocationId": "gid://shopify/CompanyLocation/1234567890"
},
"discountEntitlements": [
{
"entitled": {
"collections": ["gid://shopify/Collection/456789012345"]
},
"discount": {
"type": "PERCENTAGE",
"value": 20
}
}
]
}
POST /storefront/v1/blocks/01HQXYZ456MNO789PQR012/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 8
},
"excludeProductIds": [
"8234567890456",
"gid://shopify/Product/8234567890789"
],
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
{
"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": 1644047925,
"handle": "supreme-pouch-44370ss18a32-sm",
"updated_at": 1698280024,
"published_at": 1644047925,
"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": 8,
"page": 1,
"totalPages": 1,
"resultsPerPage": 12,
"block": {
"id": "01HQXYZ123ABC456DEF789",
"title": "Frequently Bought Together",
"anchor_type": "product",
"strategy_type": "interaction",
"strategy_key": "frequently_bought_together"
},
"attributionToken": "01JRVX9N4O5P6Q7R8S9T0U1V2W",
"_meta": {},
"_workflow": []
}
Blocks
Blocks API: Get Block Products
Blocks API endpoint that returns product recommendations for a specific block using its configured strategy, fallback chain, and merchandising rules.
POST
/
blocks
/
{blockId}
/
products
Blocks API: Get Block Products
curl --request POST \
--url https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
--data '
{
"anchor_id": "<string>",
"anchor_handle": "<string>",
"variant_id": 123,
"attributes": [
"<string>"
],
"excludeProductIds": [
"<string>"
],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": [
"<string>"
],
"retrieveFacetCount": true,
"includeFacetRanges": true,
"enrichFacetMetaobjects": 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>"
},
"context": {
"geo": {
"country": "<string>",
"province": "<string>",
"city": "<string>"
},
"productsInCart": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<string>",
"variantId": "<string>",
"options": {}
}
],
"productsPurchased": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {}
}
],
"priorSearches": [
{
"searchQuery": "<string>",
"hadClick": true,
"hasResults": true,
"fromPage": "<string>"
}
],
"marketing": {
"source": "<string>",
"medium": "<string>",
"campaign": "<string>",
"term": "<string>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": true,
"returning": true,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [
{}
],
"segments": [
{}
]
},
"market": "<string>",
"session": {
"returning": true
},
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
},
"responseOptions": {
"mediaPreloads": {
"enabled": true,
"srcsetSizes": [
123
],
"sizes": "<string>"
}
}
}
'import requests
url = "https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products"
payload = {
"anchor_id": "<string>",
"anchor_handle": "<string>",
"variant_id": 123,
"attributes": ["<string>"],
"excludeProductIds": ["<string>"],
"filter_group": {},
"pagination": {
"page": 123,
"limit": 123
},
"facets": ["<string>"],
"retrieveFacetCount": True,
"includeFacetRanges": True,
"enrichFacetMetaobjects": 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>"
},
"context": {
"geo": {
"country": "<string>",
"province": "<string>",
"city": "<string>"
},
"productsInCart": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {},
"quantity": 123
}
],
"freeShippingThreshold": 123,
"productsViewed": [
{
"id": "<string>",
"at": 123,
"title": "<string>",
"type": "<string>",
"variantId": "<string>",
"options": {}
}
],
"productsPurchased": [
{
"title": "<string>",
"price": 123,
"type": "<string>",
"productId": "<string>",
"variantId": "<string>",
"options": {}
}
],
"priorSearches": [
{
"searchQuery": "<string>",
"hadClick": True,
"hasResults": True,
"fromPage": "<string>"
}
],
"marketing": {
"source": "<string>",
"medium": "<string>",
"campaign": "<string>",
"term": "<string>",
"content": "<string>",
"clickIds": {},
"referrer": "<string>",
"landingPath": "<string>",
"channel": "<string>"
},
"experiments": {},
"customer": {
"signedIn": True,
"returning": True,
"numberOfOrders": 123,
"averageOrderValue": 123,
"daysBetweenOrders": 123,
"daysSinceLastOrder": 123,
"daysSinceOldestOrder": 123,
"totalSpent": 123,
"tags": [{}],
"segments": [{}]
},
"market": "<string>",
"session": { "returning": True },
"locale": "<string>",
"currency": "<string>",
"b2bCompany": "<string>",
"shoppingChannel": "<string>",
"custom": {}
},
"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({
anchor_id: '<string>',
anchor_handle: '<string>',
variant_id: 123,
attributes: ['<string>'],
excludeProductIds: ['<string>'],
filter_group: {},
pagination: {page: 123, limit: 123},
facets: ['<string>'],
retrieveFacetCount: true,
includeFacetRanges: true,
enrichFacetMetaobjects: 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>'
},
context: {
geo: {country: '<string>', province: '<string>', city: '<string>'},
productsInCart: [
{
title: '<string>',
price: 123,
type: '<string>',
productId: '<string>',
variantId: '<string>',
options: {},
quantity: 123
}
],
freeShippingThreshold: 123,
productsViewed: [
{
id: '<string>',
at: 123,
title: '<string>',
type: '<string>',
variantId: '<string>',
options: {}
}
],
productsPurchased: [
{
title: '<string>',
price: 123,
type: '<string>',
productId: '<string>',
variantId: '<string>',
options: {}
}
],
priorSearches: [
{
searchQuery: '<string>',
hadClick: true,
hasResults: true,
fromPage: '<string>'
}
],
marketing: {
source: '<string>',
medium: '<string>',
campaign: '<string>',
term: '<string>',
content: '<string>',
clickIds: {},
referrer: '<string>',
landingPath: '<string>',
channel: '<string>'
},
experiments: {},
customer: {
signedIn: true,
returning: true,
numberOfOrders: 123,
averageOrderValue: 123,
daysBetweenOrders: 123,
daysSinceLastOrder: 123,
daysSinceOldestOrder: 123,
totalSpent: 123,
tags: [{}],
segments: [{}]
},
market: '<string>',
session: {returning: true},
locale: '<string>',
currency: '<string>',
b2bCompany: '<string>',
shoppingChannel: '<string>',
custom: {}
},
responseOptions: {mediaPreloads: {enabled: true, srcsetSizes: [123], sizes: '<string>'}}
})
};
fetch('https://app.uselayers.com/api/storefront/v1/blocks/{blockId}/products', 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/blocks/{blockId}/products",
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([
'anchor_id' => '<string>',
'anchor_handle' => '<string>',
'variant_id' => 123,
'attributes' => [
'<string>'
],
'excludeProductIds' => [
'<string>'
],
'filter_group' => [
],
'pagination' => [
'page' => 123,
'limit' => 123
],
'facets' => [
'<string>'
],
'retrieveFacetCount' => true,
'includeFacetRanges' => true,
'enrichFacetMetaobjects' => 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>'
],
'context' => [
'geo' => [
'country' => '<string>',
'province' => '<string>',
'city' => '<string>'
],
'productsInCart' => [
[
'title' => '<string>',
'price' => 123,
'type' => '<string>',
'productId' => '<string>',
'variantId' => '<string>',
'options' => [
],
'quantity' => 123
]
],
'freeShippingThreshold' => 123,
'productsViewed' => [
[
'id' => '<string>',
'at' => 123,
'title' => '<string>',
'type' => '<string>',
'variantId' => '<string>',
'options' => [
]
]
],
'productsPurchased' => [
[
'title' => '<string>',
'price' => 123,
'type' => '<string>',
'productId' => '<string>',
'variantId' => '<string>',
'options' => [
]
]
],
'priorSearches' => [
[
'searchQuery' => '<string>',
'hadClick' => true,
'hasResults' => true,
'fromPage' => '<string>'
]
],
'marketing' => [
'source' => '<string>',
'medium' => '<string>',
'campaign' => '<string>',
'term' => '<string>',
'content' => '<string>',
'clickIds' => [
],
'referrer' => '<string>',
'landingPath' => '<string>',
'channel' => '<string>'
],
'experiments' => [
],
'customer' => [
'signedIn' => true,
'returning' => true,
'numberOfOrders' => 123,
'averageOrderValue' => 123,
'daysBetweenOrders' => 123,
'daysSinceLastOrder' => 123,
'daysSinceOldestOrder' => 123,
'totalSpent' => 123,
'tags' => [
[
]
],
'segments' => [
[
]
]
],
'market' => '<string>',
'session' => [
'returning' => true
],
'locale' => '<string>',
'currency' => '<string>',
'b2bCompany' => '<string>',
'shoppingChannel' => '<string>',
'custom' => [
]
],
'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/blocks/{blockId}/products"
payload := strings.NewReader("{\n \"anchor_id\": \"<string>\",\n \"anchor_handle\": \"<string>\",\n \"variant_id\": 123,\n \"attributes\": [\n \"<string>\"\n ],\n \"excludeProductIds\": [\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 \"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 \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n },\n \"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/blocks/{blockId}/products")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.body("{\n \"anchor_id\": \"<string>\",\n \"anchor_handle\": \"<string>\",\n \"variant_id\": 123,\n \"attributes\": [\n \"<string>\"\n ],\n \"excludeProductIds\": [\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 \"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 \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n },\n \"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/blocks/{blockId}/products")
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 \"anchor_id\": \"<string>\",\n \"anchor_handle\": \"<string>\",\n \"variant_id\": 123,\n \"attributes\": [\n \"<string>\"\n ],\n \"excludeProductIds\": [\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 \"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 \"quantity\": 123\n }\n ],\n \"freeShippingThreshold\": 123,\n \"productsViewed\": [\n {\n \"id\": \"<string>\",\n \"at\": 123,\n \"title\": \"<string>\",\n \"type\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"productsPurchased\": [\n {\n \"title\": \"<string>\",\n \"price\": 123,\n \"type\": \"<string>\",\n \"productId\": \"<string>\",\n \"variantId\": \"<string>\",\n \"options\": {}\n }\n ],\n \"priorSearches\": [\n {\n \"searchQuery\": \"<string>\",\n \"hadClick\": true,\n \"hasResults\": true,\n \"fromPage\": \"<string>\"\n }\n ],\n \"marketing\": {\n \"source\": \"<string>\",\n \"medium\": \"<string>\",\n \"campaign\": \"<string>\",\n \"term\": \"<string>\",\n \"content\": \"<string>\",\n \"clickIds\": {},\n \"referrer\": \"<string>\",\n \"landingPath\": \"<string>\",\n \"channel\": \"<string>\"\n },\n \"experiments\": {},\n \"customer\": {\n \"signedIn\": true,\n \"returning\": true,\n \"numberOfOrders\": 123,\n \"averageOrderValue\": 123,\n \"daysBetweenOrders\": 123,\n \"daysSinceLastOrder\": 123,\n \"daysSinceOldestOrder\": 123,\n \"totalSpent\": 123,\n \"tags\": [\n {}\n ],\n \"segments\": [\n {}\n ]\n },\n \"market\": \"<string>\",\n \"session\": {\n \"returning\": true\n },\n \"locale\": \"<string>\",\n \"currency\": \"<string>\",\n \"b2bCompany\": \"<string>\",\n \"shoppingChannel\": \"<string>\",\n \"custom\": {}\n },\n \"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/blocks/01HQXYZ123ABC456DEF789/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US",
"province": "California"
},
"productsInCart": [
{
"title": "Nike Air Force 1",
"productId": "8234567890123",
"variantId": "45678901234567"
}
],
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"deviceId": "device-uuid"
}
}
POST /storefront/v1/blocks/01HQXYZ654STU321VWX098/products
{
"anchor_id": "gid://shopify/Article/556677889900",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ789GHI012JKL345/products
{
"anchor_id": "summer-collection",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ789GHI012JKL345/products
{
"anchor_id": "summer-collection",
"pagination": {
"page": 1,
"limit": 20
},
"filter_group": {
"conditional": "AND",
"expressions": [
{
"property": "available",
"operator": "=",
"values": [true]
}
]
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
}
}
POST /storefront/v1/blocks/01HQXYZ456MNO789PQR012/products
{
"pagination": {
"page": 1,
"limit": 8
},
"context": {
"geo": {
"country": "US"
},
"productsInCart": [
{
"title": "Nike Air Force 1",
"productId": "8234567890123",
"variantId": "45678901234567"
},
{
"title": "Classic Tee",
"productId": "8234567890456",
"variantId": "45678901234890"
}
],
"shoppingChannel": "app"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"market": "CA",
"geo": {
"country": "CA"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"customerId": "8123456789",
"companyLocationId": "gid://shopify/CompanyLocation/1234567890"
},
"discountEntitlements": [
{
"entitled": {
"collections": ["gid://shopify/Collection/456789012345"]
},
"discount": {
"type": "PERCENTAGE",
"value": 20
}
}
]
}
POST /storefront/v1/blocks/01HQXYZ456MNO789PQR012/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 8
},
"excludeProductIds": [
"8234567890456",
"gid://shopify/Product/8234567890789"
],
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
{
"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": 1644047925,
"handle": "supreme-pouch-44370ss18a32-sm",
"updated_at": 1698280024,
"published_at": 1644047925,
"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": 8,
"page": 1,
"totalPages": 1,
"resultsPerPage": 12,
"block": {
"id": "01HQXYZ123ABC456DEF789",
"title": "Frequently Bought Together",
"anchor_type": "product",
"strategy_type": "interaction",
"strategy_key": "frequently_bought_together"
},
"attributionToken": "01JRVX9N4O5P6Q7R8S9T0U1V2W",
"_meta": {},
"_workflow": []
}
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
string
required
The unique identifier (ULID) of the block you wish to retrieve products for.When sourcing the block from a block metaobject in a Shopify theme, note that the metaobject’s
system.handle is layers-<lowercase block ID>, not the raw ID. Transform it (handle | remove_first: 'layers-' | upcase) before passing it here. Passing the prefixed handle matches no block and returns 404 with "Block not found".Body
string
The anchor identifier for the block. Required for product, article, and collection anchor types.
- Product anchors: Numeric product ID (e.g.,
"8234567890123") or Shopify GID (e.g.,"gid://shopify/Product/8234567890123"). Both formats are resolved automatically. - Article anchors: Numeric article ID (e.g.,
"556677889900") or Shopify GID (e.g.,"gid://shopify/Article/556677889900"). Both formats are resolved automatically. - Collection anchors: Collection ID (e.g.,
"456789012345") or collection handle (e.g.,"summer-collection"). The system automatically resolves both numeric IDs and string handles. - Cart anchors: Not required. Layers uses every
context.productsInCartentry with a validproductId, removes duplicates, and preserves cart order. Entries without aproductIdare skipped. - Home, Search, Not Found, Landing, Other anchors: Not required. These surfaces rely on the
contextandidentityparameters (search query, landing source, shopper context) to drive strategy selection. Search-anchored strategies (searched_then_viewed,searched_then_purchased) resolve their query from the lastsearchQueryincontext.priorSearches, not fromanchor_id, so callers must passcontext: { priorSearches: [{ searchQuery }] }for those blocks to return results. - None anchors: Not required (global blocks)
string
Deprecated: Use
anchor_id instead. For collection anchors, anchor_id now accepts both collection IDs and handles.integer
The ID of the specific variant the shopper is viewing on the anchor product. Only used for product-anchored blocks running a variant-aware strategy:
- Similar Products: the block seeds similarity from that variant instead of the product as a whole, so recommendations reflect the variant’s visual and semantic attributes, such as the selected color.
- Metafield References with a variant-scoped metafield: the block reads the reference metafield from that variant, falling back to the anchor product’s product-scoped value when the variant has none.
- Photographed Together: when the variant has photography of its own, the set is built from those shots, so shoppers on a specific colorway see the items it was styled with.
- The block’s anchor type is not
product. - The variant does not belong to the anchor product.
- The block’s strategy is not variant-aware.
variant_id is set on a product-anchored similar-products block, 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 except opt-in attributes noted below. 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. The collection_titles attribute is opt-in: pass it in attributes to include the array of collection titles each product belongs to. It is excluded from responses by default. 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]).string[]
A list of product IDs to exclude from the recommendations returned by this block. Use this to deduplicate products across multiple blocks rendered on the same page. For example, you can prevent the same product from appearing in both a “Frequently Bought Together” block and a “Customers Also Viewed” block.Each entry can be either a numeric product ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123"). Both formats are accepted and resolved automatically.Excluded products are filtered out before strategy ranking, safeguard checks, and fallback evaluation. If excluding products causes the primary block to fall below its minimum products safeguard, the fallback chain is used and exclusions are applied to fallback blocks as well.object
Storefront endpoints accept nested
AND/OR filter groups up to two levels deep. Each nested group must contain at least one expression; empty nested groups are rejected. Metafield filter properties may include hyphens in their namespace or key, for example metafields.my-app.fit-type.Refer to the dedicated Filter Expressions guide to learn more about filter expressions.filter_group.
Pagination Object
string[]
Facets to be included. Accepts both exact facet codes (e.g.,
"vendor", "options.Size") and wildcard patterns (e.g., "options.*", "metafields.product.*").Wildcard patterns expand to all matching attribute codes. For example, "options.*" expands to all option facets like "options.Size" and "options.Color". Wildcards must match at least one attribute code to be valid.Examples:// Exact facet codes
"facets": ["vendor", "options.Size", "options.Color"]
// Wildcard pattern
"facets": ["options.*"]
// Mixed exact and wildcard
"facets": ["vendor", "options.*", "metafields.product.*"]
boolean
If the count of each facet value should be calculated.
boolean
If you want a min/max range for numeric facets such as price.
boolean
When
true, any facet backed by a metaobject_reference or list.metaobject_reference metafield is returned with a companion facetDisplay object. Each entry maps a facet value (the metaobject handle) to the referenced metaobject’s display_name and fields. When the metaobject defines a color or image field, the entry also carries a resolved swatch object.Use this when your storefront filter UI needs human-readable labels or nested field data (for example, a color name or swatch hex) instead of the raw handle. When false or omitted, only the handles are returned in facets.Values are looked up from the local metaobject cache. Handles with no matching cached metaobject are omitted from facetDisplay and remain as plain values in facets. See Metaobjects and reference metafields for the normalized shape of each entry.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.Fixed amounts use your shop’s base currency. Layers skips them on market pricing rows in a different native currency, without converting the discount. Percentage discounts still apply to those localized prices. A variant that falls back to its base price can still receive a fixed-amount discount.
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. Maximum 250 entries.
string[] | number[]
Array of variant IDs that qualify for the discount. Maximum 250 entries.
string[]
Array of collection handles that qualify for the discount. Maximum 250 entries.
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
required
Defines the discount to apply.
object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
Show Properties
Show Properties
string
Persistent browser identifier that remains constant across sessions. Used to recognize returning visitors for long-term personalization. Automatically generated and managed by the Storefront Pixel.
string
Temporary session identifier. Layers-generated sessions expire after 30 minutes without activity. The Storefront Pixel refreshes the rolling window at page load and on every route change, including pages without tracked events. When a legacy Shopify or fallback cookie is available, Layers prefers it and does not control its lifetime. Without consent, the pixel uses a sessionStorage or in-memory fallback and does not write an analytics cookie.
string
Shopify customer ID for authenticated users. Only present when the customer is signed in to their account.
string
Shopify B2B company location GID (e.g.
gid://shopify/CompanyLocation/123456789) for the authenticated buyer. Layers resolves the catalog assigned to the company location and uses it to scope results: only products in the catalog are returned, prices come from the catalog’s price list, and excluded collections return 404. Omit for retail (DTC) traffic.When you pass companyLocationId, you must also pass the buyer’s customerId. Layers verifies with Shopify that the customer belongs to the company that owns the location before resolving the catalog; unauthorized or unauthenticated requests return a 403. See B2B catalogs.object
Contextual information about the customer’s session, behavior, and environment. Automatically collected by the Storefront Pixel; must be manually provided for headless integrations. See Contextual Information for implementation guidance.
Show Properties
Show Properties
object
Geographic location information for regional personalization and merchandising. Layers determines it from the IP address for client-side requests. For server-side API calls (headless integrations), provide
geo explicitly.array
Products currently in the customer’s cart. Used to surface complementary products and influence relevance scoring.
Show Array Item Properties
Show Array Item Properties
string
Product title. Each entry needs at least a
productId, variantId, or non-empty title. Layers drops entries with none of these.number
Unit price in the request currency’s major units (e.g.
29.00 for $29), not cents. Accepts a JSON number or a numeric string such as "29.00".string
Product type or category.
string
Product identifier. Accepts a numeric ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").string
Product variant identifier.
object
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).integer
Number of units of this line in the cart. Layers rounds fractional values down to a whole number. Missing values, non-numeric values, and values below
1 count as 1. Layers uses it to calculate the cart subtotal for Free Shipping Picks.number
The cart subtotal at which the shopper qualifies for free shipping, in the request currency’s major units (e.g.
75.00 for $75), not cents. Layers ignores values that aren’t a number greater than 0. Required for Free Shipping Picks blocks.Shopify’s
/cart.js and Liquid money values such as cart.total_price and item.price are in cents. Divide them by 100 before sending productsInCart[].price or freeShippingThreshold.array
Products the shopper has viewed during the current session. Layers uses these as short-lived personalization signals, with recent views weighted more heavily. Only the 20 most recent views are used. The Storefront Pixel populates this automatically; send it manually only for headless integrations. See Recently viewed products.
Show Array Item Properties
Show Array Item Properties
string
Product identifier. Accepts a numeric ID or a Shopify GID. Also accepted as
productId.integer
Timestamp of the view in Unix milliseconds. Views without
at still count but skip recency weighting.string
Product title.
string
Product type or category.
string
Variant identifier, if the shopper viewed a specific variant.
object
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).array
Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.
Show Array Item Properties
Show Array Item Properties
string
Product title. Each entry needs at least a
productId, variantId, or non-empty title. Layers drops entries with none of these.number
Unit price in the request currency’s major units (e.g.
29.00 for $29), not cents, at time of purchase. Accepts a JSON number or a numeric string such as "29.00".string
Product type or category.
string
Product identifier. Accepts a numeric ID (e.g.,
"8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").string
Product variant identifier.
object
Product variant options (e.g.,
{"Size": "11", "Color": "Red"}).array
Recent search queries and their outcomes. Helps understand customer intent and refine relevance models.
Show Array Item Properties
Show Array Item Properties
string
required
The search query text.
boolean
default:"false"
Whether the customer clicked on any results from this search.
boolean
default:"false"
Whether the search returned any results.
string
The page the search was started from (e.g., the referring page URL or page type). Layers accepts this field but doesn’t currently use it for ranking or rules.
object
UTM parameters and marketing campaign information for attribution tracking.
Show Properties
Show Properties
string
Marketing source (e.g., “google”, “facebook”).
string
Marketing medium (e.g., “cpc”, “email”, “social”).
string
Campaign name.
string
Search term or keyword.
string
Ad or link variant, such as the value of
utm_content.object
Click identifiers from the landing URL, keyed by parameter name (e.g.,
fbclid, gclid). Layers derives the originating network from them as marketing.clickSource and discards the raw tokens. See Context data structure.string
Host or URL of the site that linked the shopper to the storefront (e.g., “google.com”). Layers normalizes it to a lowercase host without
www..string
Storefront path the shopper first landed on this visit (e.g., “/collections/sale”). Layers removes the query string and keeps up to 512 characters.
string
Arrival channel. Layers derives it from UTMs, click identifiers, and the referring site, and keeps a value you send only when it can’t derive one. See Arrival channel.
object
A/B test assignments for the shopper, keyed by experiment ID with the assigned group ID as the value (e.g.,
{"exp_123": "group_b"}). Used by the Experiment Group contextual condition. The Layers app embed fills this from Intelligems automatically; values your storefront sends for the same experiment take precedence. Entries whose value isn’t a string are dropped.object
Aggregated customer behavior and purchase patterns for personalization.
Show Properties
Show Properties
boolean
Whether the customer is currently authenticated.
boolean
Whether this is a returning customer.
integer
Total number of orders placed.
number
Average order value in store currency.
integer
Average days between orders.
integer
Days since the most recent order.
integer
Days since the first order.
number
Total amount spent in store currency.
array
Shopify customer tags on the shopper’s profile (e.g.,
["vip", "wholesale"]). Collected by the Storefront Pixel for signed-in customers; null for guests.array
Shopify customer segment IDs the shopper belongs to. Server-resolved: Layers populates this from the signed-in
identity.customerId on every request and ignores any value you send. null for guests and customers with no segment memberships. Available as context.customer.segments in contextual conditions.string
Explicitly set the Shopify Market for this request. Must be provided inside
context; it is not a top-level request body parameter. Used for market-specific product availability filtering and contextual pricing. Accepts a two-letter country code (e.g., "US", "CA"), a numeric Shopify Market ID (e.g., "12345"), or a Shopify Market GID (e.g., "gid://shopify/Market/12345").When not provided, the market is automatically resolved from context.geo.country (or the shopper’s detected country for client-side requests). If no matching market is found, the store’s primary market is used as the fallback.When you send a two-letter country code that belongs to the resolved market, Layers also prices for that country, ahead of the shopper’s detected location. See Market resolution.Behavior depends on the store’s market application mode (set under Settings > Search & Discovery > Search Behavior, in the Markets card):- Restrict to market catalog — Products are filtered to only those available in the resolved market, and market-specific pricing is applied
- Adjust pricing only — The full catalog remains visible, but variant prices are swapped to market-specific values where available
- Ignore markets (default) — Market resolution is skipped entirely; base catalog and base pricing are used for all shoppers
object
Session-level signals about the current visit.
Show Properties
Show Properties
boolean
Whether the current session belongs to a returning visitor. Layers derives this from the storefront’s session cookie when not provided.
string
Storefront locale code (e.g.,
"en", "fr", "pt-br"). Case-insensitive; Layers normalizes to lowercase. When the locale is published in Shopify and served by the resolved market, Layers returns translated display text (titles, descriptions, option values, filter labels) while IDs, prices, and filter values stay in the source language. Regional locales fall back to their base language (pt-br uses pt). The store’s primary locale returns source text. See Translations.string
ISO 4217 currency code (e.g.,
"USD", "EUR"). Case-insensitive; Layers normalizes to uppercase. When Layers can resolve a currency from the shopper’s market or pricing context, the server-resolved value takes precedence.string
Shopify B2B company location identifier. When
identity.companyLocationId is provided, Layers resolves the company location server-side and the server value takes precedence.string
default:"web"
The shopping channel the customer is browsing from. Used for channel-specific merchandising, sorting, and analytics segmentation. Automatically detected from request headers when not provided (e.g., mobile app requests via Tapcart, Fuego, or Mobiloud Canvas are detected as
"app").Accepted values:"web"— Standard web browser (default)"app"— Mobile app (e.g., Tapcart, Fuego, Mobiloud Canvas)
object
Custom contextual data specific to your implementation. Structure is flexible and can contain any key-value pairs relevant to your use case.
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. Each comma-separated entry may carry a media condition, including the last entry. See the accepted format for details. The API rejects invalid values with a validation error.{
"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 the locations in the store’s inventory location scope, which is all locations by default. 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.
When the store has the Expose Variant Inventory setting enabled, variant data in block responses (both
first_or_matched_variant and variants) includes the inventory_quantity, inventory_policy, and inventory_levels fields. This behavior is consistent across all storefront API endpoints: search, browse, and blocks. See Variant Schema Fields for details on these fields.number
The total number of results. When a maximum products safeguard is configured, this value is capped to the maximum. When variant breakouts are enabled, this reflects the count of tiles (both product and variant tiles) rather than just products.
number
The current page number.
number
The total number of pages. Calculated from
totalResults and the requested page size. When a maximum products safeguard is configured, this reflects the capped total. When variant breakouts are enabled, the calculation is based on tile count.number
The number of results per page (matches the
limit parameter from the request).object
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.object
If
includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.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 block requests with analytics events via the Beacon API.
object
Information about the block that generated these recommendations.
Show Properties
Show Properties
string
The block ID.
string
The customer-facing title of the block.
string
The anchor type of the block:
product, article, collection, cart, home, search, not_found, landing, other, or none.string
The strategy type used:
interaction, similar_products, manual, metafield_reference, sequence, personalized, trending, contextual, set, or related_content.string
The specific strategy key. For product strategies:
frequently_bought_together, customers_also_viewed, customers_also_added_to_cart, viewed_then_bought, customers_also_bought. For collection strategies: browsed_then_bought, browsed_then_viewed, collection_trending. For trending strategies: best_sellers, trending_in_region, live_feed. For contextual strategies: searched_then_viewed, searched_then_purchased, landing_page_picks, free_shipping_picks. For similar products strategies on article anchors: similar_to_article. For related content strategies: related_articles.boolean
Present and set to
true when the block’s strategy data is still being computed or the strategy doesn’t yet have enough signal to return results. This applies to interaction strategies during their initial computation and to trending and contextual strategies that are warming up. It also applies to Photographed Together blocks while image detection is still processing your catalog. In this state, the primary block returns empty results and the fallback chain is used instead. Once the strategy data is ready, this field is no longer included in the response.object
Show Properties
Show Properties
array of objects
Array of variant breakout configurations applied to this block. Only present when one or more variant breakouts are active. Multiple breakouts with different option codes can work simultaneously. Each object has the structure
{optionCode: "Stone"}.Show Properties
Show Properties
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
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
object
The entitlement criteria that qualified products for the discount. Contains any of
all, products, variants, collections, or conditions. See the entitlement criteria reference.array of objects
An ordered trace of processing steps the engine performed to produce results. Each entry represents a stage in the pipeline, recorded in the order it was executed.See the Text Search documentation for the full list of possible step types.
Hidden blocks return an empty success
If an active block is hidden and has no usable fallback, the API returns HTTP200 with empty results, not a 404. For example, a matching Hide Block rule can produce this response. Treat it as a successful request with nothing to display.
The response preserves the requested page and page size, the attribution token, and the block’s identity:
{
"results": [],
"totalResults": 0,
"totalPages": 0,
"page": 1,
"resultsPerPage": 8,
"attributionToken": "01K8A2B3C4D5E6F7G8H9J0K1M2",
"block": {
"id": "01K8A2B3C4D5E6F7G8H9J0K1M3",
"title": "You may also like",
"anchor_type": "product",
"result_type": "products"
},
"_meta": {
"experimentsRan": []
}
}
block. Missing or inactive blocks still return 404, and a configuration that can’t resolve a required sort order still returns 422.
Content block responses
Blocks configured with the related content strategy return articles or pages inresults instead of products. Each item has this shape:
{
"__typename": "Article",
"content_type": "article",
"content_id": 556677889900,
"title": "How to care for linen",
"handle": "how-to-care-for-linen",
"summary_text": "Keep your linen pieces looking new with these care tips.",
"author": "Jamie Lee",
"tags": ["care", "linen"],
"image": {
"url": "https://cdn.shopify.com/s/files/1/0588/3677/9194/articles/linen-care.jpg",
"width": 1200,
"height": 800,
"alt": "Folded linen shirts"
},
"published_at": "2026-08-14T09:00:00Z",
"blog_title": "The Journal",
"url": "/blogs/the-journal/how-to-care-for-linen"
}
__typename is Article or Page depending on the block’s configured content_type. Pages don’t have author, tags, or blog_title, so those fields are null for page results.
Pagination fields (totalResults, page, totalPages, resultsPerPage), attributionToken, and the block object work the same as for product blocks. Product-only request parameters (filter_group, variant_id, attributes, facets, and discountEntitlements) don’t apply to content blocks.
Anchor and strategy compatibility
Strategy compatibility depends on the anchor type. See the strategy availability by anchor type matrix for the complete list of supported strategies. Requests that use a strategy type not allowed for the anchor are rejected with a validation error onstrategy_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. |
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). |
Block concepts
For details on how blocks work conceptually (anchor types, strategies, rules, safeguards, and fallback chains), see the platform documentation:Error handling
string
Error message when the request fails.
404 - Block not found
404 - Block not found
The specified block ID doesn’t exist or is not active.
{
"error": "Block not found"
}
422 - Sort order required
422 - Sort order required
The block’s configuration didn’t resolve to a valid sort order. This can happen with collection-anchored similar-products blocks when the configured fallback sort order no longer exists. Reconfigure the block with a valid sort order in the dashboard, then retry the request.
{
"error": "A sort order code or ID is required to load this block."
}
401 - Unauthorized
401 - Unauthorized
Invalid or missing authentication token.
402 - Store suspended
402 - Store suspended
The store is suspended. Every storefront API request returns
402 until the suspension is lifted.{
"message": "This store has been suspended."
}
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US",
"province": "California"
},
"productsInCart": [
{
"title": "Nike Air Force 1",
"productId": "8234567890123",
"variantId": "45678901234567"
}
],
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"deviceId": "device-uuid"
}
}
POST /storefront/v1/blocks/01HQXYZ654STU321VWX098/products
{
"anchor_id": "gid://shopify/Article/556677889900",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ789GHI012JKL345/products
{
"anchor_id": "summer-collection",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ789GHI012JKL345/products
{
"anchor_id": "summer-collection",
"pagination": {
"page": 1,
"limit": 20
},
"filter_group": {
"conditional": "AND",
"expressions": [
{
"property": "available",
"operator": "=",
"values": [true]
}
]
},
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
}
}
POST /storefront/v1/blocks/01HQXYZ456MNO789PQR012/products
{
"pagination": {
"page": 1,
"limit": 8
},
"context": {
"geo": {
"country": "US"
},
"productsInCart": [
{
"title": "Nike Air Force 1",
"productId": "8234567890123",
"variantId": "45678901234567"
},
{
"title": "Classic Tee",
"productId": "8234567890456",
"variantId": "45678901234890"
}
],
"shoppingChannel": "app"
},
"identity": {
"sessionId": "abc123"
}
}
POST /storefront/v1/blocks/01HQXYZ123ABC456DEF789/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 12
},
"context": {
"market": "CA",
"geo": {
"country": "CA"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123",
"customerId": "8123456789",
"companyLocationId": "gid://shopify/CompanyLocation/1234567890"
},
"discountEntitlements": [
{
"entitled": {
"collections": ["gid://shopify/Collection/456789012345"]
},
"discount": {
"type": "PERCENTAGE",
"value": 20
}
}
]
}
POST /storefront/v1/blocks/01HQXYZ456MNO789PQR012/products
{
"anchor_id": "8234567890123",
"pagination": {
"page": 1,
"limit": 8
},
"excludeProductIds": [
"8234567890456",
"gid://shopify/Product/8234567890789"
],
"context": {
"geo": {
"country": "US"
},
"shoppingChannel": "web"
},
"identity": {
"sessionId": "abc123"
}
}
{
"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": 1644047925,
"handle": "supreme-pouch-44370ss18a32-sm",
"updated_at": 1698280024,
"published_at": 1644047925,
"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": 8,
"page": 1,
"totalPages": 1,
"resultsPerPage": 12,
"block": {
"id": "01HQXYZ123ABC456DEF789",
"title": "Frequently Bought Together",
"anchor_type": "product",
"strategy_type": "interaction",
"strategy_key": "frequently_bought_together"
},
"attributionToken": "01JRVX9N4O5P6Q7R8S9T0U1V2W",
"_meta": {},
"_workflow": []
}
See also
- Blocks Platform Documentation - Learn about block concepts and configuration
Was this page helpful?