Search Products
curl --request POST \
--url https://{base-address}/discovery/search \
--header 'Content-Type: application/json' \
--header 'x-environment-id: <x-environment-id>' \
--header 'x-tenant-id: <x-tenant-id>' \
--header 'x-workspace-id: <x-workspace-id>' \
--data '
{
"facets": [
{
"field": "brand",
"value": {
"value": "Nike"
}
},
{
"field": "price",
"value": {
"min": 20,
"max": 200
}
}
],
"filters": [
{
"action": "equals",
"field": "brand",
"value": "Nike"
}
],
"fields": [
"<string>"
],
"selected_variant_fields": [
"<string>"
],
"skip": 123,
"limit": 123,
"sort_by": "price",
"sort_order": "desc",
"include_count": true,
"is_auto_spell_correction": true,
"is_auto_spell_correction_zero_results": true,
"did_you_mean_limit": 123,
"session_id": "<string>",
"user_id": "<string>",
"currency": "<string>",
"currency_conversion_rate": 123,
"location": "<string>",
"price_group": "<string>",
"auto_redirect": true,
"skip_facet_generation": true,
"variation_map_group_by": [
{
"name": "Color",
"field": "color"
}
],
"variation_map_group_values": [
{
"name": "min_price",
"aggregation": "Min",
"field": "price",
"value": "<string>"
}
]
}
'import requests
url = "https://{base-address}/discovery/search"
payload = {
"facets": [
{
"field": "brand",
"value": { "value": "Nike" }
},
{
"field": "price",
"value": {
"min": 20,
"max": 200
}
}
],
"filters": [
{
"action": "equals",
"field": "brand",
"value": "Nike"
}
],
"fields": ["<string>"],
"selected_variant_fields": ["<string>"],
"skip": 123,
"limit": 123,
"sort_by": "price",
"sort_order": "desc",
"include_count": True,
"is_auto_spell_correction": True,
"is_auto_spell_correction_zero_results": True,
"did_you_mean_limit": 123,
"session_id": "<string>",
"user_id": "<string>",
"currency": "<string>",
"currency_conversion_rate": 123,
"location": "<string>",
"price_group": "<string>",
"auto_redirect": True,
"skip_facet_generation": True,
"variation_map_group_by": [
{
"name": "Color",
"field": "color"
}
],
"variation_map_group_values": [
{
"name": "min_price",
"aggregation": "Min",
"field": "price",
"value": "<string>"
}
]
}
headers = {
"x-tenant-id": "<x-tenant-id>",
"x-workspace-id": "<x-workspace-id>",
"x-environment-id": "<x-environment-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-tenant-id': '<x-tenant-id>',
'x-workspace-id': '<x-workspace-id>',
'x-environment-id': '<x-environment-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
facets: [
{field: 'brand', value: {value: 'Nike'}},
{field: 'price', value: {min: 20, max: 200}}
],
filters: [{action: 'equals', field: 'brand', value: 'Nike'}],
fields: ['<string>'],
selected_variant_fields: ['<string>'],
skip: 123,
limit: 123,
sort_by: 'price',
sort_order: 'desc',
include_count: true,
is_auto_spell_correction: true,
is_auto_spell_correction_zero_results: true,
did_you_mean_limit: 123,
session_id: '<string>',
user_id: '<string>',
currency: '<string>',
currency_conversion_rate: 123,
location: '<string>',
price_group: '<string>',
auto_redirect: true,
skip_facet_generation: true,
variation_map_group_by: [{name: 'Color', field: 'color'}],
variation_map_group_values: [{name: 'min_price', aggregation: 'Min', field: 'price', value: '<string>'}]
})
};
fetch('https://{base-address}/discovery/search', 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://{base-address}/discovery/search",
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([
'facets' => [
[
'field' => 'brand',
'value' => [
'value' => 'Nike'
]
],
[
'field' => 'price',
'value' => [
'min' => 20,
'max' => 200
]
]
],
'filters' => [
[
'action' => 'equals',
'field' => 'brand',
'value' => 'Nike'
]
],
'fields' => [
'<string>'
],
'selected_variant_fields' => [
'<string>'
],
'skip' => 123,
'limit' => 123,
'sort_by' => 'price',
'sort_order' => 'desc',
'include_count' => true,
'is_auto_spell_correction' => true,
'is_auto_spell_correction_zero_results' => true,
'did_you_mean_limit' => 123,
'session_id' => '<string>',
'user_id' => '<string>',
'currency' => '<string>',
'currency_conversion_rate' => 123,
'location' => '<string>',
'price_group' => '<string>',
'auto_redirect' => true,
'skip_facet_generation' => true,
'variation_map_group_by' => [
[
'name' => 'Color',
'field' => 'color'
]
],
'variation_map_group_values' => [
[
'name' => 'min_price',
'aggregation' => 'Min',
'field' => 'price',
'value' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-environment-id: <x-environment-id>",
"x-tenant-id: <x-tenant-id>",
"x-workspace-id: <x-workspace-id>"
],
]);
$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://{base-address}/discovery/search"
payload := strings.NewReader("{\n \"facets\": [\n {\n \"field\": \"brand\",\n \"value\": {\n \"value\": \"Nike\"\n }\n },\n {\n \"field\": \"price\",\n \"value\": {\n \"min\": 20,\n \"max\": 200\n }\n }\n ],\n \"filters\": [\n {\n \"action\": \"equals\",\n \"field\": \"brand\",\n \"value\": \"Nike\"\n }\n ],\n \"fields\": [\n \"<string>\"\n ],\n \"selected_variant_fields\": [\n \"<string>\"\n ],\n \"skip\": 123,\n \"limit\": 123,\n \"sort_by\": \"price\",\n \"sort_order\": \"desc\",\n \"include_count\": true,\n \"is_auto_spell_correction\": true,\n \"is_auto_spell_correction_zero_results\": true,\n \"did_you_mean_limit\": 123,\n \"session_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"currency\": \"<string>\",\n \"currency_conversion_rate\": 123,\n \"location\": \"<string>\",\n \"price_group\": \"<string>\",\n \"auto_redirect\": true,\n \"skip_facet_generation\": true,\n \"variation_map_group_by\": [\n {\n \"name\": \"Color\",\n \"field\": \"color\"\n }\n ],\n \"variation_map_group_values\": [\n {\n \"name\": \"min_price\",\n \"aggregation\": \"Min\",\n \"field\": \"price\",\n \"value\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-tenant-id", "<x-tenant-id>")
req.Header.Add("x-workspace-id", "<x-workspace-id>")
req.Header.Add("x-environment-id", "<x-environment-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{base-address}/discovery/search")
.header("x-tenant-id", "<x-tenant-id>")
.header("x-workspace-id", "<x-workspace-id>")
.header("x-environment-id", "<x-environment-id>")
.header("Content-Type", "application/json")
.body("{\n \"facets\": [\n {\n \"field\": \"brand\",\n \"value\": {\n \"value\": \"Nike\"\n }\n },\n {\n \"field\": \"price\",\n \"value\": {\n \"min\": 20,\n \"max\": 200\n }\n }\n ],\n \"filters\": [\n {\n \"action\": \"equals\",\n \"field\": \"brand\",\n \"value\": \"Nike\"\n }\n ],\n \"fields\": [\n \"<string>\"\n ],\n \"selected_variant_fields\": [\n \"<string>\"\n ],\n \"skip\": 123,\n \"limit\": 123,\n \"sort_by\": \"price\",\n \"sort_order\": \"desc\",\n \"include_count\": true,\n \"is_auto_spell_correction\": true,\n \"is_auto_spell_correction_zero_results\": true,\n \"did_you_mean_limit\": 123,\n \"session_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"currency\": \"<string>\",\n \"currency_conversion_rate\": 123,\n \"location\": \"<string>\",\n \"price_group\": \"<string>\",\n \"auto_redirect\": true,\n \"skip_facet_generation\": true,\n \"variation_map_group_by\": [\n {\n \"name\": \"Color\",\n \"field\": \"color\"\n }\n ],\n \"variation_map_group_values\": [\n {\n \"name\": \"min_price\",\n \"aggregation\": \"Min\",\n \"field\": \"price\",\n \"value\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{base-address}/discovery/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-tenant-id"] = '<x-tenant-id>'
request["x-workspace-id"] = '<x-workspace-id>'
request["x-environment-id"] = '<x-environment-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"facets\": [\n {\n \"field\": \"brand\",\n \"value\": {\n \"value\": \"Nike\"\n }\n },\n {\n \"field\": \"price\",\n \"value\": {\n \"min\": 20,\n \"max\": 200\n }\n }\n ],\n \"filters\": [\n {\n \"action\": \"equals\",\n \"field\": \"brand\",\n \"value\": \"Nike\"\n }\n ],\n \"fields\": [\n \"<string>\"\n ],\n \"selected_variant_fields\": [\n \"<string>\"\n ],\n \"skip\": 123,\n \"limit\": 123,\n \"sort_by\": \"price\",\n \"sort_order\": \"desc\",\n \"include_count\": true,\n \"is_auto_spell_correction\": true,\n \"is_auto_spell_correction_zero_results\": true,\n \"did_you_mean_limit\": 123,\n \"session_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"currency\": \"<string>\",\n \"currency_conversion_rate\": 123,\n \"location\": \"<string>\",\n \"price_group\": \"<string>\",\n \"auto_redirect\": true,\n \"skip_facet_generation\": true,\n \"variation_map_group_by\": [\n {\n \"name\": \"Color\",\n \"field\": \"color\"\n }\n ],\n \"variation_map_group_values\": [\n {\n \"name\": \"min_price\",\n \"aggregation\": \"Min\",\n \"field\": \"price\",\n \"value\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"records": [
{
"id": "<string>",
"name": "<string>",
"sku": "<string>",
"provider_id": "<string>",
"brand": "<string>",
"description": "<string>",
"url": "<string>",
"primary_image_url": "<string>",
"type": "<string>",
"categories": [
"<string>"
],
"category_ids": [
"<string>"
],
"tags": [
"<string>"
],
"calculated_price": 123,
"reviews_count": 123,
"option_color": "<unknown>",
"selected_variant": {
"id": "<string>",
"name": "<string>",
"sku": "<string>",
"provider_id": "<string>",
"brand": "<string>",
"description": "<string>",
"primary_image_url": "<string>",
"categories": [
"<string>"
],
"option_color": "<string>",
"calculated_price": 123
},
"variants_map": [
{
"color": "<string>",
"sku": "<string>",
"price": 123,
"swatch_color": "<string>",
"primary_image_url": "<string>",
"product_url": "<string>"
}
],
"ranking_info": {
"overall_score": 123,
"relevance_score": 123,
"merchandising_score": 123,
"performance_score": 123,
"personalization_score": 123,
"newness_score": 123,
"position": 123,
"source": "<string>",
"result_from": "<string>"
}
}
],
"facets": [
{
"name": "<string>",
"field": "<string>",
"appearance": "<string>",
"values": [
{
"value": "<string>",
"display_value": "<string>",
"count": 123,
"image_url": "<string>",
"color": "<string>",
"min": 123,
"max": 123
}
],
"range": {},
"enable_multi_select": true,
"items_to_show": 123,
"show_count": true,
"show_search_within_facet": true,
"default_collapse_on_desktop": true,
"default_collapse_on_mobile": true,
"display_tooltip": true,
"tooltip": "<string>",
"layout_style": "<string>",
"display_layout": "<string>",
"star_color": "<string>"
}
],
"banners": [
{
"id": "<string>",
"position": 123,
"repeat_on_pagination": true,
"banner": {
"hide_on_desktop": true,
"hide_on_tablet": true,
"hide_on_mobile": true,
"desktop_config": {},
"tablet_config": {},
"mobile_config": {}
}
}
],
"meta": {
"total_count": 123,
"result_source": "<string>",
"did_you_mean": [
"<string>"
],
"corrected_search_term": "<string>",
"auto_spell_correction_applied": true,
"redirect_url": "<string>",
"tagged_attributes": [
{}
],
"merchandising_rules_applied": [
{
"id": "<string>",
"variant_id": "<string>"
}
],
"is_price_filter_dropped": true,
"experiments": {}
}
}{
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}{
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}Search
Search Products
Primary product-search endpoint for the storefront. Returns the matching products, along with facets, banners, and result metadata.
Facet filters, structured filters, sorting, pagination, out-of-stock handling, variation-map grouping, and personalization context are all set in the request body.
POST
/
discovery
/
search
Search Products
curl --request POST \
--url https://{base-address}/discovery/search \
--header 'Content-Type: application/json' \
--header 'x-environment-id: <x-environment-id>' \
--header 'x-tenant-id: <x-tenant-id>' \
--header 'x-workspace-id: <x-workspace-id>' \
--data '
{
"facets": [
{
"field": "brand",
"value": {
"value": "Nike"
}
},
{
"field": "price",
"value": {
"min": 20,
"max": 200
}
}
],
"filters": [
{
"action": "equals",
"field": "brand",
"value": "Nike"
}
],
"fields": [
"<string>"
],
"selected_variant_fields": [
"<string>"
],
"skip": 123,
"limit": 123,
"sort_by": "price",
"sort_order": "desc",
"include_count": true,
"is_auto_spell_correction": true,
"is_auto_spell_correction_zero_results": true,
"did_you_mean_limit": 123,
"session_id": "<string>",
"user_id": "<string>",
"currency": "<string>",
"currency_conversion_rate": 123,
"location": "<string>",
"price_group": "<string>",
"auto_redirect": true,
"skip_facet_generation": true,
"variation_map_group_by": [
{
"name": "Color",
"field": "color"
}
],
"variation_map_group_values": [
{
"name": "min_price",
"aggregation": "Min",
"field": "price",
"value": "<string>"
}
]
}
'import requests
url = "https://{base-address}/discovery/search"
payload = {
"facets": [
{
"field": "brand",
"value": { "value": "Nike" }
},
{
"field": "price",
"value": {
"min": 20,
"max": 200
}
}
],
"filters": [
{
"action": "equals",
"field": "brand",
"value": "Nike"
}
],
"fields": ["<string>"],
"selected_variant_fields": ["<string>"],
"skip": 123,
"limit": 123,
"sort_by": "price",
"sort_order": "desc",
"include_count": True,
"is_auto_spell_correction": True,
"is_auto_spell_correction_zero_results": True,
"did_you_mean_limit": 123,
"session_id": "<string>",
"user_id": "<string>",
"currency": "<string>",
"currency_conversion_rate": 123,
"location": "<string>",
"price_group": "<string>",
"auto_redirect": True,
"skip_facet_generation": True,
"variation_map_group_by": [
{
"name": "Color",
"field": "color"
}
],
"variation_map_group_values": [
{
"name": "min_price",
"aggregation": "Min",
"field": "price",
"value": "<string>"
}
]
}
headers = {
"x-tenant-id": "<x-tenant-id>",
"x-workspace-id": "<x-workspace-id>",
"x-environment-id": "<x-environment-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-tenant-id': '<x-tenant-id>',
'x-workspace-id': '<x-workspace-id>',
'x-environment-id': '<x-environment-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
facets: [
{field: 'brand', value: {value: 'Nike'}},
{field: 'price', value: {min: 20, max: 200}}
],
filters: [{action: 'equals', field: 'brand', value: 'Nike'}],
fields: ['<string>'],
selected_variant_fields: ['<string>'],
skip: 123,
limit: 123,
sort_by: 'price',
sort_order: 'desc',
include_count: true,
is_auto_spell_correction: true,
is_auto_spell_correction_zero_results: true,
did_you_mean_limit: 123,
session_id: '<string>',
user_id: '<string>',
currency: '<string>',
currency_conversion_rate: 123,
location: '<string>',
price_group: '<string>',
auto_redirect: true,
skip_facet_generation: true,
variation_map_group_by: [{name: 'Color', field: 'color'}],
variation_map_group_values: [{name: 'min_price', aggregation: 'Min', field: 'price', value: '<string>'}]
})
};
fetch('https://{base-address}/discovery/search', 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://{base-address}/discovery/search",
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([
'facets' => [
[
'field' => 'brand',
'value' => [
'value' => 'Nike'
]
],
[
'field' => 'price',
'value' => [
'min' => 20,
'max' => 200
]
]
],
'filters' => [
[
'action' => 'equals',
'field' => 'brand',
'value' => 'Nike'
]
],
'fields' => [
'<string>'
],
'selected_variant_fields' => [
'<string>'
],
'skip' => 123,
'limit' => 123,
'sort_by' => 'price',
'sort_order' => 'desc',
'include_count' => true,
'is_auto_spell_correction' => true,
'is_auto_spell_correction_zero_results' => true,
'did_you_mean_limit' => 123,
'session_id' => '<string>',
'user_id' => '<string>',
'currency' => '<string>',
'currency_conversion_rate' => 123,
'location' => '<string>',
'price_group' => '<string>',
'auto_redirect' => true,
'skip_facet_generation' => true,
'variation_map_group_by' => [
[
'name' => 'Color',
'field' => 'color'
]
],
'variation_map_group_values' => [
[
'name' => 'min_price',
'aggregation' => 'Min',
'field' => 'price',
'value' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-environment-id: <x-environment-id>",
"x-tenant-id: <x-tenant-id>",
"x-workspace-id: <x-workspace-id>"
],
]);
$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://{base-address}/discovery/search"
payload := strings.NewReader("{\n \"facets\": [\n {\n \"field\": \"brand\",\n \"value\": {\n \"value\": \"Nike\"\n }\n },\n {\n \"field\": \"price\",\n \"value\": {\n \"min\": 20,\n \"max\": 200\n }\n }\n ],\n \"filters\": [\n {\n \"action\": \"equals\",\n \"field\": \"brand\",\n \"value\": \"Nike\"\n }\n ],\n \"fields\": [\n \"<string>\"\n ],\n \"selected_variant_fields\": [\n \"<string>\"\n ],\n \"skip\": 123,\n \"limit\": 123,\n \"sort_by\": \"price\",\n \"sort_order\": \"desc\",\n \"include_count\": true,\n \"is_auto_spell_correction\": true,\n \"is_auto_spell_correction_zero_results\": true,\n \"did_you_mean_limit\": 123,\n \"session_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"currency\": \"<string>\",\n \"currency_conversion_rate\": 123,\n \"location\": \"<string>\",\n \"price_group\": \"<string>\",\n \"auto_redirect\": true,\n \"skip_facet_generation\": true,\n \"variation_map_group_by\": [\n {\n \"name\": \"Color\",\n \"field\": \"color\"\n }\n ],\n \"variation_map_group_values\": [\n {\n \"name\": \"min_price\",\n \"aggregation\": \"Min\",\n \"field\": \"price\",\n \"value\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-tenant-id", "<x-tenant-id>")
req.Header.Add("x-workspace-id", "<x-workspace-id>")
req.Header.Add("x-environment-id", "<x-environment-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{base-address}/discovery/search")
.header("x-tenant-id", "<x-tenant-id>")
.header("x-workspace-id", "<x-workspace-id>")
.header("x-environment-id", "<x-environment-id>")
.header("Content-Type", "application/json")
.body("{\n \"facets\": [\n {\n \"field\": \"brand\",\n \"value\": {\n \"value\": \"Nike\"\n }\n },\n {\n \"field\": \"price\",\n \"value\": {\n \"min\": 20,\n \"max\": 200\n }\n }\n ],\n \"filters\": [\n {\n \"action\": \"equals\",\n \"field\": \"brand\",\n \"value\": \"Nike\"\n }\n ],\n \"fields\": [\n \"<string>\"\n ],\n \"selected_variant_fields\": [\n \"<string>\"\n ],\n \"skip\": 123,\n \"limit\": 123,\n \"sort_by\": \"price\",\n \"sort_order\": \"desc\",\n \"include_count\": true,\n \"is_auto_spell_correction\": true,\n \"is_auto_spell_correction_zero_results\": true,\n \"did_you_mean_limit\": 123,\n \"session_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"currency\": \"<string>\",\n \"currency_conversion_rate\": 123,\n \"location\": \"<string>\",\n \"price_group\": \"<string>\",\n \"auto_redirect\": true,\n \"skip_facet_generation\": true,\n \"variation_map_group_by\": [\n {\n \"name\": \"Color\",\n \"field\": \"color\"\n }\n ],\n \"variation_map_group_values\": [\n {\n \"name\": \"min_price\",\n \"aggregation\": \"Min\",\n \"field\": \"price\",\n \"value\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{base-address}/discovery/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-tenant-id"] = '<x-tenant-id>'
request["x-workspace-id"] = '<x-workspace-id>'
request["x-environment-id"] = '<x-environment-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"facets\": [\n {\n \"field\": \"brand\",\n \"value\": {\n \"value\": \"Nike\"\n }\n },\n {\n \"field\": \"price\",\n \"value\": {\n \"min\": 20,\n \"max\": 200\n }\n }\n ],\n \"filters\": [\n {\n \"action\": \"equals\",\n \"field\": \"brand\",\n \"value\": \"Nike\"\n }\n ],\n \"fields\": [\n \"<string>\"\n ],\n \"selected_variant_fields\": [\n \"<string>\"\n ],\n \"skip\": 123,\n \"limit\": 123,\n \"sort_by\": \"price\",\n \"sort_order\": \"desc\",\n \"include_count\": true,\n \"is_auto_spell_correction\": true,\n \"is_auto_spell_correction_zero_results\": true,\n \"did_you_mean_limit\": 123,\n \"session_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"currency\": \"<string>\",\n \"currency_conversion_rate\": 123,\n \"location\": \"<string>\",\n \"price_group\": \"<string>\",\n \"auto_redirect\": true,\n \"skip_facet_generation\": true,\n \"variation_map_group_by\": [\n {\n \"name\": \"Color\",\n \"field\": \"color\"\n }\n ],\n \"variation_map_group_values\": [\n {\n \"name\": \"min_price\",\n \"aggregation\": \"Min\",\n \"field\": \"price\",\n \"value\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"records": [
{
"id": "<string>",
"name": "<string>",
"sku": "<string>",
"provider_id": "<string>",
"brand": "<string>",
"description": "<string>",
"url": "<string>",
"primary_image_url": "<string>",
"type": "<string>",
"categories": [
"<string>"
],
"category_ids": [
"<string>"
],
"tags": [
"<string>"
],
"calculated_price": 123,
"reviews_count": 123,
"option_color": "<unknown>",
"selected_variant": {
"id": "<string>",
"name": "<string>",
"sku": "<string>",
"provider_id": "<string>",
"brand": "<string>",
"description": "<string>",
"primary_image_url": "<string>",
"categories": [
"<string>"
],
"option_color": "<string>",
"calculated_price": 123
},
"variants_map": [
{
"color": "<string>",
"sku": "<string>",
"price": 123,
"swatch_color": "<string>",
"primary_image_url": "<string>",
"product_url": "<string>"
}
],
"ranking_info": {
"overall_score": 123,
"relevance_score": 123,
"merchandising_score": 123,
"performance_score": 123,
"personalization_score": 123,
"newness_score": 123,
"position": 123,
"source": "<string>",
"result_from": "<string>"
}
}
],
"facets": [
{
"name": "<string>",
"field": "<string>",
"appearance": "<string>",
"values": [
{
"value": "<string>",
"display_value": "<string>",
"count": 123,
"image_url": "<string>",
"color": "<string>",
"min": 123,
"max": 123
}
],
"range": {},
"enable_multi_select": true,
"items_to_show": 123,
"show_count": true,
"show_search_within_facet": true,
"default_collapse_on_desktop": true,
"default_collapse_on_mobile": true,
"display_tooltip": true,
"tooltip": "<string>",
"layout_style": "<string>",
"display_layout": "<string>",
"star_color": "<string>"
}
],
"banners": [
{
"id": "<string>",
"position": 123,
"repeat_on_pagination": true,
"banner": {
"hide_on_desktop": true,
"hide_on_tablet": true,
"hide_on_mobile": true,
"desktop_config": {},
"tablet_config": {},
"mobile_config": {}
}
}
],
"meta": {
"total_count": 123,
"result_source": "<string>",
"did_you_mean": [
"<string>"
],
"corrected_search_term": "<string>",
"auto_spell_correction_applied": true,
"redirect_url": "<string>",
"tagged_attributes": [
{}
],
"merchandising_rules_applied": [
{
"id": "<string>",
"variant_id": "<string>"
}
],
"is_price_filter_dropped": true,
"experiments": {}
}
}{
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}{
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See Authentication & Base URLs.
Send
facets, filters, and other structured fields as real JSON here. The GET variant accepts the same fields but requires them JSON-encoded into the query string.Headers
Identifies your organization. Ensures data isolation per tenant.
Identifies the workspace within your organization. Scopes resources to a specific workspace.
Identifies the environment you are targeting. Scopes the call to a specific deployment environment.
Query Parameters
The catalog to search. Every request is scoped to a single catalog.
The shopper's search term. Leave it out to browse instead of search — combine that with category_id or collection_id to list everything in a category or collection.
Locale to run the search in, such as en-us. Determines which localized product content is matched and returned.
Restrict results to a single category, identified by its id in your commerce platform.
Restrict results to a single Experro collection, identified by its Experro collection id.
Restrict results to a single category by name rather than id. Use this when you have the category name but not its id.
Body
application/json
Facet selections used to narrow the result set. One entry per faceted field. A field that is not a configured facet on the catalog is silently ignored, so check the facets returned in the response for the field names this catalog uses — a price facet may be calculated_price rather than price.
Show child attributes
Show child attributes
Example:
[
{
"field": "brand",
"value": { "value": "Nike" }
},
{
"field": "price",
"value": { "min": 20, "max": 200 }
}
]
Filter criteria applied to the result set. Multiple entries are combined with AND, so for several conditions just add several entries. Use a group inside an entry only when you need OR logic.
Show child attributes
Show child attributes
Which product fields to return on each record. Requesting only the fields your page renders keeps responses small; omit it to get the default set.
Which variant fields to return inside selected_variant on each record.
How many matching products to skip before the first one returned. Combine with limit to page through results.
How many products to return in this page of results.
Name of the field to sort by, such as price. Leave it out to sort by relevance.
Example:
"price"
Which direction to sort in. Only meaningful together with sort_by.
asc— lowest to highest.desc— highest to lowest. This is the default.
Case-insensitive; any other value falls back to descending.
Available options:
asc, desc Return the total number of matching products in meta.total_count. Leave it off if you only need the current page.
Correct likely misspellings in q before searching, so a query such as shose still finds shoes.
Only apply spell correction when the original query returns nothing. Use this when you would rather show exact matches first and fall back to correction.
How many "did you mean" alternatives to return in meta.did_you_mean.
Identifier for the shopper's current session. Groups their search activity for analytics and personalization.
Identifier for the shopper, used for personalization and recent-search history. This is the body field, separate from any x-user-id header.
Currency to return prices in, such as USD.
Rate used to convert prices into currency when the catalog stores them in a different one.
Shopper location, used for location-aware results such as store-specific inventory or pricing.
Price group to resolve prices against, for customer-group or B2B pricing.
What to do with products that are out of stock.
Include— included and ranked normally.Exclude— removed from results entirely.Burry— included but ranked lower.
Available options:
Include, Exclude, Burry Apply any configured query redirect that matches q. When one matches, the target is returned in meta.redirect_url so your storefront can redirect the shopper.
Skip building facets for this request. Facets come back null and the response is faster — useful when you only need product records.
Group variants of the same product together so you can render one card per color or size rather than one per variant.
Show child attributes
Show child attributes
Which values to compute for each variation group, such as the first image or the lowest price. Results appear in variants_map on each record.
Show child attributes
Show child attributes
Force which variant option is shown as the product's hero image, overriding the normal selection logic.
Show child attributes
Show child attributes
Response
Success.
The product-search payload. Returned at the top level, with no envelope.
Ranked product records for the current page.
Show child attributes
Show child attributes
Facets generated for the result set. Null when skip_facet_generation is true.
Show child attributes
Show child attributes
Banners to render alongside the results. Null when none apply.
Show child attributes
Show child attributes
Result metadata for the query.
Show child attributes
Show child attributes