Recommendations API

The Recommendations API delivers the personalized and contextually relevant product recommendations based a supplied URL.

The URL is used to map and select the ‘Route’, which is used to determine which 'Widget(s)' will be returned.

• Method: GET

• URL: https://<PA_END_POINT>/3.0/recommendations

• Headers:

  • Content-Type: application/json
  • Authorization: Bearer ACCESS_TOKEN

• Query Parameters:

  • currentUrl (string) [REQUIRED]: This URL is used to determine which route to use [REQUIRED]
  • customerId (GUID): While it is optional, it is required to get personalized results such as Recently Viewed items or Viewed with Recently Viewed items.
  • expandProductDetails (boolean): Default is false. If it is not set, or is set to false, then only refId and the isInStock fields will be returned for the products in the slot. If it is set to true then the full product information will be returned for each slot. Your choice here will depend on where you choose to populate product information from.

• Returned Payload:

  {
      "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,
                              "hmac": "sample-hmac",
                              "hmacSalt": "sample-salt",
                              "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",
                                      "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"
                                          },
                                          {
                                              "name": "Color",
                                              "options": [
                                                  {
                                                      "name": "Black"
                                                  },
                                                  {
                                                      "name": "White"
                                                  }
                                              ]
                                          }
                                      ]
                                  }
                              ]
                          }
                      ]
                  }
              ]
          }
      }
  }
  • recommendations (object): Contains the selected Route object -
    • route (object): Contains following properties -
      • id (GUID): The Route ID
      • name (string): The Route name
      • widgets (array of objects): Array of widget objects, where each object contains -
        • id (GUID): Widget ID
        • name (string): Widget name
        • slots (array of object): Each slot object contains the following properties -
          • label (string): The Slot label
          • tacticId (GUID): The Tactic used to populate this slot.
          • campaignId (GUID): The Campaign used to populate this slot.
          • recommenderId (GUID): The Recommender used to populate this slot.
          • retailBoostCollectionCampaignId (GUID): The Boost Campaign ID if Boost was used for this slot.
          • products (array of object): Array of product objects. The default implementation is to return a single product per slot, so this array will contain only one Product object. The product object will either contain just the refId and the isInStock field if exapandProductDetails is not set to true. If exapandProductDetails was set to true, it will include the entire Product object as supplied via the Product API (Please see the Product API page for the product object structure).

Here’s an example code snippet using JavaScript’s Fetch API:

const url = 'https://<PA_END_POINT>/3.0/recommendations?customerId=sampleCustomerId';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token

fetch(url, {
  method: 'GET',
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  }
})
  .then(response => response.json())
  .then(data => console.log('Recommendations:', data))
  .catch(error => console.error('Error fetching recommendations:', error));

Summary:

This document is about the Recommendations API, its functionality, and usage in delivering personalized product recommendations.

• The API uses a supplied URL to determine which 'Widget(s)' will be returned and provides detailed query parameters for customization.

• The returned payload includes the selected Route object containing widget and slot details for personalized product recommendations.

• It also outlines an example code snippet using JavaScript’s Fetch API for utilizing the Recommendations API.