Response Schema Reference

This page details the structure and fields of the Recommendations API response.

Response Structure

The response from the Recommendations API follows a hierarchical structure:

Recommendation Response
└── Route Object
    └── Widgets Array
        └── Widget Object
            └── Slots Array
                └── Slot Object
                    ├── Products Array
                    │   └── Product Object
                    └── Banners Array
                        └── Banner Object
                            ├── CTAs Array
                            │   └── CTA Object
                            └── Images Array
                                └── Image Object
                                    └── Banner Image Variations Array
                                        └── Image Variation Object

Response Objects

Response Object

The top-level response object.

Field	Type	Description
recommendations	object	Container for all recommendation data, containing a Route object

Route Object

Represents a matched route based on the provided URL or routeName.

Field	Type	Description
id	GUID	Unique identifier for the route
name	string	Human-readable name of the route
widgets	array	Array of Widget objects

Widget Object

Represents a UI component within a route.

Field	Type	Description
id	GUID	Unique identifier for the widget
name	string	Human-readable name of the widget
slots	array	Array of Slot objects

Slot Object

Represents a position within a widget that contains products or banners.

Field	Type	Description
label	string	Human-readable label for the slot
tacticId	GUID	ID of the tactic used for this slot
campaignId	GUID	ID of the campaign for this slot
recommenderId	GUID	ID of the recommender for this slot
products	array	Array of Product objects
banners	array	Array of Banner objects

Slot Tracking Fields

Additional fields in the Slot object used for tracking and sponsored content:

Field	Type	Description
retailBoostCollectionCampaignId	GUID	ID for Retailer Boost campaigns
adSetId	GUID	ID of the Retail Media Ad Set
adSetVersion	integer	Version number of the Ad Set
costPerClick	string	Cost per click for this slot
costPerMille	string	Cost per thousand impressions
costPerAction	string	Cost per action for this slot
hmacSalt	string	Salt for HMAC authentication
hmac	string	Authentication code for tracking
timeStamp	long	Timestamp when slot was populated

Product Data Objects

Product Object (Basic Fields)

When expandProductDetails=false (default), only these fields are returned:

Field	Type	Description
refId	string	Product reference ID (always returned)
isInStock	boolean	Product availability status

Product Object (Extended Fields)

When expandProductDetails=true, these additional fields are returned:

Field	Type	Description
id	GUID	Internal product ID
name	string	Product name
itemGroupId	string	Item group/family ID
description	string	Product description
sku	string	Product SKU
url	string	Product URL
brand	object	Brand information object
images	array	Array of image URLs
prices	array	Array of price objects
contents	array	Array of localized content objects
attributes	array	Array of product attribute objects

Brand Object

Field	Type	Description
id	GUID	Brand ID
name	string	Brand name
logoUrl	string	URL to brand logo

Price Object

Field	Type	Description
price	number	Base price
code	string	Currency code
discountPrice	number	Discounted price (if applicable)

Content Object

Field	Type	Description
languageTag	string	Language code
name	string	Localized name
description	string	Localized description
url	string	Localized URL

Attribute Object

Product attributes use different fields based on the valueType property:

Field	Type	Description	Used When
name	string	Attribute name	Always
valueType	integer	Type of value (see below)	Always
stringValue	string	String value	valueType = 1
scalarValue	number	Numeric value	valueType = 2
options	array	Array of option objects	valueType = 3

valueType values:

• 0 = None (default fallback to String)
• 1 = String (uses stringValue property)
• 2 = Scalar (uses scalarValue property for numeric values)
• 3 = StringArray (uses options array of objects with value property)

Banner Objects

Banner Object

Represents a promotional banner that can be displayed in a slot.

Field	Type	Description
id	GUID	Unique identifier for the banner
title	string	Banner title text
titleColor	string	Color code for the title text
subTitle	string	Banner subtitle text
subTitleColor	string	Color code for the subtitle text
description	string	Banner description text
descriptionColor	string	Color code for the description text
smallPrint	string	Small print text (terms and conditions)
smallPrintColor	string	Color code for the small print text
textAlignment	string	Alignment of text (e.g., "left", "center")
backgroundColor	string	Background color code for the banner
CTAs	array	Array of CTA objects
images	array	Array of Banner Image objects

CTA Object

Represents a Call-to-Action button within a banner.

Field	Type	Description
id	GUID	Unique identifier for the CTA
enable	boolean	Whether the CTA is enabled
text	string	Text to display on the CTA button
textColor	string	Color code for the CTA text
backgroundColor	string	Background color code for the CTA
redirectUrl	string	URL to navigate to when clicked
altText	string	Alternative text for accessibility

Banner Image Object

Represents an image used within a banner.

Field	Type	Description
id	GUID	Unique identifier for the image
imageUrl	string	URL to the image
title	string	Title of the image
isFile	boolean	Whether the image is a file or URL
assetId	GUID	ID of the digital asset
altText	string	Alternative text for accessibility
containerFit	string	How image fits in container
alignment	string	Alignment of the image
bannerType	integer	Type of banner (see note below)
digitalAssetDeviceTypes	integer	Device types bit field (see note)
bannerImageVariations	array	Array of image variations for different devices

Device Types

Banner Type values:

• 1 = Desktop
• 2 = Tablet
• 3 = Mobile

Digital Asset Device Types values (bit field):

• 1 = Desktop
• 2 = Tablet
• 3 = Desktop and Tablet
• 4 = Mobile
• 5 = Desktop and Mobile
• 6 = Tablet and Mobile
• 7 = All devices (Desktop, Tablet, and Mobile)

Complete Response Example

Below is a comprehensive example showing a response with all possible fields populated:

{
  "recommendations": {
    "route": {
      "id": "sample-route-id",
      "name": "Sample Mens Clothing Route",
      "widgets": [
        {
          "id": "sample-widget-id",
          "name": "Sample Mini Cart Widget",
          "slots": [
            {
              "label": "Sample Slot 1",
              "tacticId": "sample-tactic-id",
              "campaignId": "sample-campaign-id",
              "recommenderId": "sample-recommender-id",
              "retailBoostCollectionCampaignId": "sample-boost-id",
              "adSetId": "sample-adset-id",
              "adSetVersion": 1,
              "costPerClick": "0.50",
              "costPerMille": "5.00",
              "costPerAction": "1.00",
              "hmacSalt": "sample-salt",
              "hmac": "sample-hmac",
              "timeStamp": 638469344702812000,
              "products": [
                {
                  "refId": "sample-refId",
                  "name": "Sample Product Name",
                  "description": "This is a sample product description.",
                  "sku": "SKU123ABC",
                  "url": "http://www.example.com/product/sample",
                  "isInStock": true,
                  "itemGroupId": "SAMPLE-GROUP-ID",
                  "brand": {
                    "id": "sample-brand-id",
                    "name": "Sample Brand",
                    "logoUrl": "https://www.example.com/brand-logo.jpg"
                  },
                  "images": [
                    "https://www.example.com/image1.jpg",
                    "https://www.example.com/image2.jpg",
                    "https://www.example.com/image3.jpg"
                  ],
                  "prices": [
                    {
                      "price": 123.12,
                      "code": "AUD",
                      "discountPrice": 119.5
                    },
                    {
                      "price": 67.12,
                      "code": "SGD"
                    }
                  ],
                  "contents": [
                    {
                      "languageTag": "en-AU",
                      "name": "Sample Product Name AU",
                      "description": "Description for Australian market.",
                      "url": "http://www.example.com/au/product/sample"
                    },
                    {
                      "languageTag": "ja-JP",
                      "name": "サンプル商品名",
                      "description": "日本市場向けの説明。",
                      "url": "http://www.example.com/jp/product/sample"
                    }
                  ],
                  "attributes": [
                    {
                      "name": "Material",
                      "stringValue": "Synthetic",
                      "valueType": 1
                    },
                    {
                      "name": "Color",
                      "options": [
                        {
                          "value": "Black"
                        },
                        {
                          "value": "White"
                        }
                      ],
                      "valueType": 3
                    },
                    {
                      "name": "Weight",
                      "scalarValue": 250,
                      "valueType": 2
                    }
                  ]
                }
              ],
              "banners": [
                {
                  "id": "sample-banner-id",
                  "title": "Special Offer",
                  "titleColor": "#333333",
                  "subTitle": "Limited Time Only",
                  "subTitleColor": "#666666",
                  "description": "Get 20% off on all products",
                  "descriptionColor": "#666666",
                  "smallPrint": "Terms and conditions apply",
                  "smallPrintColor": "#999999",
                  "textAlignment": "center",
                  "backgroundColor": "#FFFFFF",
                  "retailerId": "sample-retailer-id",
                  "supplierId": "sample-supplier-id",
                  "RBCCID": "sample-rbcc-id",
                  "ADSID": "sample-ads-id",
                  "ADSVN": 1,
                  "CPC": "0.50",
                  "CPA": "1.00",
                  "CPM": "5.00",
                  "HMACSalt": "sample-hmac-salt",
                  "HMAC": "sample-hmac",
                  "TimeStamp": 638469344702812000,
                  "PlacementId": "sample-placement-id",
                  "CTAs": [
                    {
                      "id": "sample-cta-id",
                      "enable": true,
                      "text": "Shop Now",
                      "textColor": "#FFFFFF",
                      "backgroundColor": "#FF5500",
                      "redirectUrl": "https://www.example.com/shop",
                      "altText": "Shop the collection"
                    }
                  ],
                  "images": [
                    {
                      "id": "sample-image-id",
                      "imageUrl": "https://www.example.com/banner.jpg",
                      "title": "Banner Image",
                      "isFile": true,
                      "assetId": "sample-asset-id",
                      "altText": "Special offer banner",
                      "containerFit": "cover",
                      "alignment": "center",
                      "bannerType": 1,
                      "digitalAssetDeviceTypes": 1,
                      "bannerImageVariations": [
                        {
                          "id": "sample-variation-id",
                          "imageUrl": "https://www.example.com/banner-mobile.jpg",
                          "title": "Mobile Banner Image",
                          "isFile": true,
                          "assetId": "sample-asset-id-mobile",
                          "bannerType": 3,
                          "digitalAssetDeviceTypes": 4
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}