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

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

When includeWidgetDetails=true, these additional fields are returned:

Field	Type	Description
`type`	`integer`	Widget type identifier
`numberOfSlots`	`integer`	Number of slots in the widget
`header`	`object`	Widget header configuration object

Field	Type	Description
`title`	`object`	Title configuration object

Field	Type	Description
`collapsed`	`object`	Collapsed state configuration
`expanded`	`object`	Expanded state configuration

Field	Type	Description
`desktop`	`string`	Desktop configuration value
`mobile`	`string`	Mobile configuration value

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
`placementId`	`GUID?`	ID of the placement
`supplierId`	`GUID?`	ID of the supplier

Product Data Objects

Product Object (Basic Fields)

When expandProductDetails=false (default), only this field is returned:

Field	Type	Description
`refId`	`string`	Product reference ID (always returned)

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
`isInStock`	`boolean?`	Product availability status
`source`	`string`	Product source information
`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`	`decimal`	Base price
`code`	`string`	Currency code
`discountPrice`	`decimal?`	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`	`string`	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
`json`	`boolean`	Whether value is JSON format	Always

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)

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
`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
`position`	`int`	Position/order of the CTA

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`	`string`	Type of banner (see note below)
`digitalAssetDeviceTypes`	`string`	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)

Image Variation Object

Represents a variation of a banner image for different devices.

Field	Type	Description
`id`	`GUID`	Unique identifier for the variation
`imageUrl`	`string`	URL to the variation image
`title`	`string`	Title of the variation 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`	`string`	Type of banner (see note above)
`digitalAssetDeviceTypes`	`string`	Device types bit field (see note above)

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",
          "type": 1,
          "numberOfSlots": 1,
          "header": {
            "title": {
              "collapsed": {
                "desktop": "Sample Widget",
                "mobile": "Sample Widget"
              },
              "expanded": {
                "desktop": "Sample Mini Cart Widget",
                "mobile": "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,
              "placementId": "sample-placement-id",
              "supplierId": "sample-supplier-id",
              "products": [
                {
                  "id": "sample-product-id",
                  "refId": "sample-refId",
                  "name": "Sample Product Name",
                  "itemGroupId": "SAMPLE-GROUP-ID",
                  "description": "This is a sample product description.",
                  "sku": "SKU123ABC",
                  "url": "http://www.example.com/product/sample",
                  "isInStock": true,
                  "source": "sample-source",
                  "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",
                      "scalarValue": null,
                      "json": false,
                      "options": null,
                      "valueType": "1"
                    },
                    {
                      "name": "Color",
                      "stringValue": null,
                      "scalarValue": null,
                      "json": false,
                      "options": [
                        {
                          "value": "Black"
                        },
                        {
                          "value": "White"
                        }
                      ],
                      "valueType": "3"
                    },
                    {
                      "name": "Weight",
                      "stringValue": null,
                      "scalarValue": 250,
                      "json": false,
                      "options": null,
                      "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",
                  "smallPrint": "Terms and conditions apply",
                  "smallPrintColor": "#999999",
                  "textAlignment": "center",
                  "backgroundColor": "#FFFFFF",
                  "ctas": [
                    {
                      "id": "sample-cta-id",
                      "enable": true,
                      "text": "Shop Now",
                      "textColor": "#FFFFFF",
                      "backgroundColor": "#FF5500",
                      "redirectUrl": "https://www.example.com/shop",
                      "altText": "Shop the collection",
                      "position": 1
                    }
                  ],
                  "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",
                          "altText": "Mobile special offer banner",
                          "containerFit": "cover",
                          "alignment": "center",
                          "bannerType": "3",
                          "digitalAssetDeviceTypes": "4"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Response Schema Reference

Response Structure

Response Objects

Response Object

Route Object

Widget Object

Widget Extended Fields

Widget Header Object

Widget Title Configuration Object

Widget State Configuration Object

Slot Object

Slot Tracking Fields

Product Data Objects

Product Object (Basic Fields)

Product Object (Extended Fields)

Brand Object

Price Object

Content Object

Attribute Object

Banner Objects

Banner Object

CTA Object

Banner Image Object

Image Variation Object

Complete Response Example

Response Structure​

Response Objects​

Response Object​

Route Object​

Widget Object​

Widget Extended Fields​

Widget Header Object​

Widget Title Configuration Object​

Widget State Configuration Object​

Slot Object​

Slot Tracking Fields​

Product Data Objects​

Product Object (Basic Fields)​

Product Object (Extended Fields)​

Brand Object​

Price Object​

Content Object​

Attribute Object​

Banner Objects​

Banner Object​

CTA Object​

Banner Image Object​

Image Variation Object​

Complete Response Example​

Response Structure

Response Objects

Response Object

Route Object

Widget Object

Widget Extended Fields

Widget Header Object

Widget Title Configuration Object

Widget State Configuration Object

Slot Object

Slot Tracking Fields

Product Data Objects

Product Object (Basic Fields)

Product Object (Extended Fields)

Brand Object

Price Object

Content Object

Attribute Object

Banner Objects

Banner Object

CTA Object

Banner Image Object

Image Variation Object

Complete Response Example