Get Recommendations for a Widget Context
curl --request POST \
--url https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId} \
--header 'Content-Type: application/json' \
--data '
{
"context_type": "<string>",
"context_data": "<string>",
"product_ids": [
"<string>"
],
"category_ids": [
"<string>"
],
"user_id": "<string>",
"filter": [
{
"group": {
"operator": "<string>",
"rules": [
{
"action": "<string>",
"field_name": "<string>",
"value": "<string>"
}
]
}
}
]
}
'import requests
url = "https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}"
payload = {
"context_type": "<string>",
"context_data": "<string>",
"product_ids": ["<string>"],
"category_ids": ["<string>"],
"user_id": "<string>",
"filter": [{ "group": {
"operator": "<string>",
"rules": [
{
"action": "<string>",
"field_name": "<string>",
"value": "<string>"
}
]
} }]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
context_type: '<string>',
context_data: '<string>',
product_ids: ['<string>'],
category_ids: ['<string>'],
user_id: '<string>',
filter: [
{
group: {
operator: '<string>',
rules: [{action: '<string>', field_name: '<string>', value: '<string>'}]
}
}
]
})
};
fetch('https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}', 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}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}",
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([
'context_type' => '<string>',
'context_data' => '<string>',
'product_ids' => [
'<string>'
],
'category_ids' => [
'<string>'
],
'user_id' => '<string>',
'filter' => [
[
'group' => [
'operator' => '<string>',
'rules' => [
[
'action' => '<string>',
'field_name' => '<string>',
'value' => '<string>'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$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}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}"
payload := strings.NewReader("{\n \"context_type\": \"<string>\",\n \"context_data\": \"<string>\",\n \"product_ids\": [\n \"<string>\"\n ],\n \"category_ids\": [\n \"<string>\"\n ],\n \"user_id\": \"<string>\",\n \"filter\": [\n {\n \"group\": {\n \"operator\": \"<string>\",\n \"rules\": [\n {\n \"action\": \"<string>\",\n \"field_name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ]\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
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}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}")
.header("Content-Type", "application/json")
.body("{\n \"context_type\": \"<string>\",\n \"context_data\": \"<string>\",\n \"product_ids\": [\n \"<string>\"\n ],\n \"category_ids\": [\n \"<string>\"\n ],\n \"user_id\": \"<string>\",\n \"filter\": [\n {\n \"group\": {\n \"operator\": \"<string>\",\n \"rules\": [\n {\n \"action\": \"<string>\",\n \"field_name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ]\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"context_type\": \"<string>\",\n \"context_data\": \"<string>\",\n \"product_ids\": [\n \"<string>\"\n ],\n \"category_ids\": [\n \"<string>\"\n ],\n \"user_id\": \"<string>\",\n \"filter\": [\n {\n \"group\": {\n \"operator\": \"<string>\",\n \"rules\": [\n {\n \"action\": \"<string>\",\n \"field_name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ]\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"Status": "success",
"Data": {
"records": [
{
"id": "<string>",
"tenant_id": "<string>",
"workspace_id": "<string>",
"content_model_id": "<string>",
"content_model_data_id": "<string>",
"version_no": 123,
"version_name": "<string>",
"language": [
"<string>"
],
"modified_by": "<string>",
"modified_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"store_id": "<string>",
"channel_id": [
"<string>"
],
"_version_": "<string>",
"in_stock": 123,
"brand_page_slug": "<string>",
"revenue": 123,
"category_ids": [
"<string>"
],
"variants_sku_count": 123,
"sku_for_analytics": [
"<string>"
],
"provider": "<string>",
"provider_id": "<string>",
"images": [
{
"id": "<string>",
"product_id": "<string>",
"is_thumbnail": true,
"sort_order": 123,
"description": "<string>",
"image_file": "<string>",
"url_zoom": "<string>",
"url_standard": "<string>",
"url_thumbnail": "<string>",
"url_tiny": "<string>",
"date_modified": "2023-11-07T05:31:56Z"
}
],
"price": 123,
"description": "<string>",
"sku": "<string>",
"type": "<string>",
"name": "<string>",
"page_slug": "<string>",
"page_title": "<string>",
"menu_title": "<string>",
"condition": [
"<string>"
],
"sort_order": 123,
"is_price_hidden": true,
"availability": "<string>",
"upc": "<string>",
"warranty": "<string>",
"is_featured": true,
"is_visible": true,
"is_free_shipping": true,
"fixed_cost_shipping_price": 123,
"inventory_tracking": "<string>",
"inventory_warning_level": 123,
"inventory_level": 123,
"brand": "<string>",
"brand_id": "<string>",
"product_tax_code": "<string>",
"tax_class_id": "<string>",
"map_price": 123,
"sale_price": 123,
"retail_price": 123,
"cost_price": 123,
"height": 123,
"depth": 123,
"width": 123,
"weight": 123
}
],
"_meta_": {
"tenant_id": "<string>",
"workspace_id": "<string>",
"env_type": "<string>",
"store_hash": "<string>",
"content_model_id": "<string>",
"_fields_": {}
}
}
}{
"Status": "failure",
"Data": {
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}
}{
"Status": "failure",
"Data": {
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}
}{
"Status": "failure",
"Data": {
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}
}Discovery APIs
Recommendation Widget
Returns personalized product recommendations for the specified widget based on the provided context (e.g., current product, category, or cart contents). Supports optional filtering and pagination.
POST
/
apis
/
ecommerce-service
/
public
/
recommendation
/
v2
/
widgets
/
{widgetId}
Get Recommendations for a Widget Context
curl --request POST \
--url https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId} \
--header 'Content-Type: application/json' \
--data '
{
"context_type": "<string>",
"context_data": "<string>",
"product_ids": [
"<string>"
],
"category_ids": [
"<string>"
],
"user_id": "<string>",
"filter": [
{
"group": {
"operator": "<string>",
"rules": [
{
"action": "<string>",
"field_name": "<string>",
"value": "<string>"
}
]
}
}
]
}
'import requests
url = "https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}"
payload = {
"context_type": "<string>",
"context_data": "<string>",
"product_ids": ["<string>"],
"category_ids": ["<string>"],
"user_id": "<string>",
"filter": [{ "group": {
"operator": "<string>",
"rules": [
{
"action": "<string>",
"field_name": "<string>",
"value": "<string>"
}
]
} }]
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
context_type: '<string>',
context_data: '<string>',
product_ids: ['<string>'],
category_ids: ['<string>'],
user_id: '<string>',
filter: [
{
group: {
operator: '<string>',
rules: [{action: '<string>', field_name: '<string>', value: '<string>'}]
}
}
]
})
};
fetch('https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}', 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}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}",
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([
'context_type' => '<string>',
'context_data' => '<string>',
'product_ids' => [
'<string>'
],
'category_ids' => [
'<string>'
],
'user_id' => '<string>',
'filter' => [
[
'group' => [
'operator' => '<string>',
'rules' => [
[
'action' => '<string>',
'field_name' => '<string>',
'value' => '<string>'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$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}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}"
payload := strings.NewReader("{\n \"context_type\": \"<string>\",\n \"context_data\": \"<string>\",\n \"product_ids\": [\n \"<string>\"\n ],\n \"category_ids\": [\n \"<string>\"\n ],\n \"user_id\": \"<string>\",\n \"filter\": [\n {\n \"group\": {\n \"operator\": \"<string>\",\n \"rules\": [\n {\n \"action\": \"<string>\",\n \"field_name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ]\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
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}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}")
.header("Content-Type", "application/json")
.body("{\n \"context_type\": \"<string>\",\n \"context_data\": \"<string>\",\n \"product_ids\": [\n \"<string>\"\n ],\n \"category_ids\": [\n \"<string>\"\n ],\n \"user_id\": \"<string>\",\n \"filter\": [\n {\n \"group\": {\n \"operator\": \"<string>\",\n \"rules\": [\n {\n \"action\": \"<string>\",\n \"field_name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ]\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{base-address}/apis/ecommerce-service/public/recommendation/v2/widgets/{widgetId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"context_type\": \"<string>\",\n \"context_data\": \"<string>\",\n \"product_ids\": [\n \"<string>\"\n ],\n \"category_ids\": [\n \"<string>\"\n ],\n \"user_id\": \"<string>\",\n \"filter\": [\n {\n \"group\": {\n \"operator\": \"<string>\",\n \"rules\": [\n {\n \"action\": \"<string>\",\n \"field_name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ]\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"Status": "success",
"Data": {
"records": [
{
"id": "<string>",
"tenant_id": "<string>",
"workspace_id": "<string>",
"content_model_id": "<string>",
"content_model_data_id": "<string>",
"version_no": 123,
"version_name": "<string>",
"language": [
"<string>"
],
"modified_by": "<string>",
"modified_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"store_id": "<string>",
"channel_id": [
"<string>"
],
"_version_": "<string>",
"in_stock": 123,
"brand_page_slug": "<string>",
"revenue": 123,
"category_ids": [
"<string>"
],
"variants_sku_count": 123,
"sku_for_analytics": [
"<string>"
],
"provider": "<string>",
"provider_id": "<string>",
"images": [
{
"id": "<string>",
"product_id": "<string>",
"is_thumbnail": true,
"sort_order": 123,
"description": "<string>",
"image_file": "<string>",
"url_zoom": "<string>",
"url_standard": "<string>",
"url_thumbnail": "<string>",
"url_tiny": "<string>",
"date_modified": "2023-11-07T05:31:56Z"
}
],
"price": 123,
"description": "<string>",
"sku": "<string>",
"type": "<string>",
"name": "<string>",
"page_slug": "<string>",
"page_title": "<string>",
"menu_title": "<string>",
"condition": [
"<string>"
],
"sort_order": 123,
"is_price_hidden": true,
"availability": "<string>",
"upc": "<string>",
"warranty": "<string>",
"is_featured": true,
"is_visible": true,
"is_free_shipping": true,
"fixed_cost_shipping_price": 123,
"inventory_tracking": "<string>",
"inventory_warning_level": 123,
"inventory_level": 123,
"brand": "<string>",
"brand_id": "<string>",
"product_tax_code": "<string>",
"tax_class_id": "<string>",
"map_price": 123,
"sale_price": 123,
"retail_price": 123,
"cost_price": 123,
"height": 123,
"depth": 123,
"width": 123,
"weight": 123
}
],
"_meta_": {
"tenant_id": "<string>",
"workspace_id": "<string>",
"env_type": "<string>",
"store_hash": "<string>",
"content_model_id": "<string>",
"_fields_": {}
}
}
}{
"Status": "failure",
"Data": {
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}
}{
"Status": "failure",
"Data": {
"Status": "failure",
"Error": {
"message": "<string>",
"name": "<string>",
"code": "<string>"
}
}
}{
"Status": "failure",
"Data": {
"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.
Headers
Optional customer group identifier for segment-specific responses.
eCommerce provider for contextualizing the API call (e.g., shopify, magento, etc.).
Path Parameters
Unique identifier of the widget to retrieve.
Query Parameters
Comma-separated list of fields to include in the response
Specifies the language or region for the response data
Identifier of the store within the eCommerce platform.
Sales or distribution channel identifier.
Identifier for the regional location from the BigCommerce admin panel.
Currency code for price displays.
Whether to include metadata about the fields in the response. If true, returns metadata for each filterable field.
Number of items to skip for pagination offset.
Maximum number of items to return.
Body
application/json
Specify the type of context for the request (e.g., product, category, web_pages, cart, etc)
Context-specific data, relevant to the context_type
List of product IDs to seed “similar items” recommendations.
List of category IDs to seed category-based recommendations.
Unique identifier for the user or user email.
Query filter expression to narrow results
Show child attributes
Show child attributes
⌘I