Skip to content

Recommendation best practices

Voyado Elevate offers multiple recommendation algorithms. They can be used or applied in different parts of a site. This guide provides suggestions on which Elevate recommendations would suit which part of a site. To learn more about including recommendation lists on a page, see Page configurations.

Note on API Library examples

For more information on how to get up and running with the API library, see JavaScript API Library.

Overview

The table below shows the mapping between the recommendations and where on a site to use them. It is important to understand the mapping is a suggestion and not a restriction for POST requests. When configuring pages in the Experience app, the available algorithms are limited to TOP_PRODUCTS, PERSONAL, NEWEST_PRODUCTS, RECENTLY_VIEWED, and FAVORITES since they target landing pages exclusively.

Algorithm Where to use?
ADD_TO_CART_RECS Add-to-cart popup
ALTERNATIVES Product details page
CART Cart/Checkout page
FAVORITES Homepage or Landing page
MORE_FROM_SERIES Product details page
NEWEST_PRODUCTS Homepage or a Landing page (likely dedicated to new arrivals)
PERSONAL Homepage or Landing page
RECENTLY_VIEWED Product details page or Landing page
STYLE_WITH Product details page
TOP_PRODUCTS Homepage
UPSELL Product details page

Add to cart recs

The add-to-cart recommendation is suitable to use in a popup that is displayed after the visitor has added an item to the cart. The variant that the visitor added to the cart is declared in the variantKey in the query parameter. It uses previously notified add-to-cart to know what is in the cart.

Example

//request-body.json
{
  "recommendationLists": [
    {
      "id": "ATC-1",
      "algorithm": "ADD_TO_CART_RECS"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/add-to-cart-popup?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&variantKey=AD_0589_P_549_015_XS" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.addToCartPopup(
  { variantKey: 'AD_0589_P_549_015_XS' },
  [{
    id: 'ATC-1',
    algorithm: 'ADD_TO_CART_RECS'
  }]
);

Alternatives

The Alternatives recommendation is suitable to use on a product details page. It returns products that are visually and functionally similar to the product the visitor is viewing. The product that the visitor is viewing is declared in the productKey in the query parameter.

Example

//request-body.json
{
  "productGroup" : {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "ALTERNATIVES"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{{cluster-id}}.api.esales.apptus.cloud/api/storefront/v3/queries/product-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&productKey=AD_0682_P_290_011" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.productPage(
  { productKey: 'AD_0682_P_290_011' },
  {
    productGroup : {
      include: true
    },
    recommendationLists: [
      {
        id: 'PDP-1',
        algorithm: 'ALTERNATIVES'
      }
    ]
  }
);

Cart

The Cart recommendation is suitable to use on a cart or a checkout page. It returns products that are likely to be bought based on the products in the visitor's current cart.

Example

//request-body.json
{
  "recommendationLists": [
    {
      "id": "CART-1",
      "algorithm": "CART"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/cart-page?cart=AD_0589_P_549_015_XS%7CAD_0738_P_913_002_27&market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP"  \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const res = await api.query.cartPage(
  {
    cart: ['AD_0589_P_549_015_XS', 'AD_0738_P_913_002_27']
  }, {
    recommendationLists: [{
      id: 'CART-1', algorithm: 'CART'
    }]
  }
);

Favorite

The Favorite recommendation is suitable to use on the homepage or on a landing page. It returns products based on what a visitor has added to their favorite list; not the favorite list itself. It is important to remember that this recommendation performs better when there is a visitor with a known behavior that is identified via a customer key. For more information about identifying visitors, see Visitor identification.

Example

//request-body.json
{
  "recommendationLists": [
    {
      "id": "FAV-1",
      "algorithm": "FAVORITES"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/landing-page?market=US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageReference=/" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.landingPage(
  { pageReference: '/' },
  {
    recommendationLists: [
      { id: 'FAV-1', algorithm: 'FAVORITES' }
    ]
  }
);

More from series

The More from series recommendation is suitable to use on a product detail page. More from series returns products that belong to the same series as the source product. The productKey must be supplied in the query parameter for Elevate to list products from the same series. If that product does not belong to a series, the list will be empty. The series is defined in the data feed, using the series attribute. Series are global for the entire product catalog, so if two brands have the same name of a series attribute names can be used in v3 and translations in v4, for example the series id value can be the series name concatenated with the brand for example "Billy Ikea" for the series id and "Billy" for the series name.

Example

//request-body.json
{
  "productGroup" : {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "MORE_FROM_SERIES"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{{cluster-id}}.api.esales.apptus.cloud/api/storefront/v3/queries/product-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&productKey=AD_0682_P_290_011" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.productPage(
  { productKey:'AD_0682_P_290_011' },
  {
    productGroup : { include: true },
    recommendationLists: [
      { id: 'PDP-1', algorithm: 'MORE_FROM_SERIES' }
    ]
  }
);

Newest product

The Newest Product recommendation is suitable to use on a landing page dedicated for new arrivals. It returns products sorted by newness. Elevate determines newness based on the release_date attribute supplied in the data feed.

Example

//request-body.json
{ 
  "recommendationLists": [
    {
      "id": "NEW-1",
      "algorithm": "NEWEST_PRODUCTS"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/landing-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageReference=/new-arrival" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.landingPage(
  { pageReference: '/new-arrival' },
  {
    recommendationLists: [
      { id: 'NEW-1', algorithm: 'NEWEST_PRODUCTS' }
    ]
  }
);

Personal

The Personal recommendation is suitable for use on the homepage or a landing page. It returns products related to what a visitor has interacted with. It is important to remember that this recommendation performs better when there is a visitor with a known behavior that is identified via a customer key. The recommendation backfills with products from the Top products recommendation. For more information about identifying visitors, see Visitor identification.

Example

//request-body.json
{
  "recommendationLists": [
    {
      "id": "PERSONAL-1",
      "algorithm": "PERSONAL"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/landing-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageReference=/new-arrival" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.landingPage(
  { pageReference: '/' },
  {
    recommendationLists: [
      { id: 'PERSONAL-1', algorithm: 'PERSONAL' }
    ]
  }
);

Recently viewed

The Recently viewed recommendation returns products recently viewed by the visitor. This recommendation type can, like other recommendation types, be used on any landing pages and product detail pages. And just like other recommendation types, Recently Viewed supports product rules for including or excluding products.

Example

//request-body.json
{
  "recommendationLists": [
    {
      "id": "RECENTLY_VIEWED-1",
      "algorithm": "RECENTLY_VIEWED"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/landing-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageReference=/new-arrival" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.landingPage(
  { pageReference: '/' },
  {
    recommendationLists: [
      { id: 'RECENTLY_VIEWED-1', algorithm: 'RECENTLY_VIEWED' }
    ]
  }
);

Style with

The Style with recommendation is suitable to use on a product details page. It returns products that go well together with the product currently viewed by a visitor. For example, a visitor is on the product detail page of a digital camera. The camera goes together with a certain type of accessories such as lens, a battery, and a cable. The product currently viewed is declared in the productKey in the query parameter. The products that go together must be specified in the data feed using the style_with attribute.

Example of Style With Recommendation

Example

//request-body.json
{
  "productGroup" : {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "STYLE_WITH"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{{cluster-id}}.api.esales.apptus.cloud/api/storefront/v3/queries/product-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&productKey=AD_0682_P_290_011" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.productPage(
  { productKey:'AD_0682_P_290_011' },
  {
    productGroup : { include: true },
    recommendationLists: [
      { id: 'PDP-1', algorithm: 'STYLE_WITH' }
    ]
  }
);

Top products

The Top products recommendation is suitable to use on the homepage. It returns the most relevant products based on all visitors' interactions, stock level, newness, and selected exposure strategy.

Example

//request-body.json
{
  "recommendationLists": [
    {
      "id": "TOP-1",
      "algorithm": "TOP_PRODUCTS"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/landing-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageReference=/new-arrival" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.landingPage(
  { pageReference: '/' },
  {
    recommendationLists: [
      { id: 'TOP-1', algorithm: 'TOP_PRODUCTS' }
    ]
  }
);

Upsell

The Upsell recommendation is suitable to use on a product detail page. It returns recommendations that are complementary to or likely to be bought together with the viewed product, or likely to be considered by other visitors. The productKey must be supplied in the query parameter for Elevate to recommend other complementary products.

Example

//request-body.json
{
  "productGroup" : {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "UPSELL"
    }
  ]
}

#!/bin/bash
curl -X POST \
"https://{{cluster-id}}.api.esales.apptus.cloud/api/storefront/v3/queries/product-page?market=US&locale=en-US&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&productKey=AD_0682_P_290_011" \
-H 'Content-Type: application/json' \
-d @request-body.json

const api = elevate({ clusterId: 'w00000000', market: 'US', locale: 'en-US', touchpoint: 'desktop', session: () => userKeys });
const results = await api.query.productPage(
  { productKey:'AD_0682_P_290_011' },
  {
    productGroup : { include: true },
    recommendationLists: [
      { id: 'PDP-1', algorithm: 'UPSELL' }
    ]
  }
);

Tips

Combine recommendations

It is possible to combine two or more recommendations if relevant. For example, ALTERNATIVES and can be combined with UPSELL on a product detail page. The homepage can include TOP_PRODUCTS and PERSONAL or FAVORITES. These combinations can be specified in the request body when sending a POST request.

Below is an example of a page configuration where the ALTERNATIVES and UPSELL recommendations are used.

  {
    "recommendationLists": [
      {
        "id": "PDP-1",
        "algorithm": "ALTERNATIVES"
      },
      {
        "id": "PDP-2",
        "algorithm": "UPSELL"
      }
    ]
  }

Targeted recommendations

Apply product rules to have a more focused selection of product recommendations. For example, when using TOP_PRODUCTS or NEWEST_PRODUCTS recommendation, the recommendation can be limited to certain price range or certain categories. Product rules can be specified in the body of a page configuration.

Below is an example where the NEWEST_PRODUCTS recommendation is limited to the Kitchen supplies department/category. This example is relevant to apply for a landing page that highlights new arrivals within a specific category. 

  {
    "recommendationLists": [{
      "id": "rec-1",
      "algorithm": "NEWEST_PRODUCTS",
      "productRules":  "rule incl department {\"Kitchen\"}"
    }]
  }

Below is an example where the TOP_PRODUCTS recommendation is limited to products with prices up to 150 in the local currency.

  {
    "recommendationLists": [{
      "id": "rec-2",
      "algorithm": "TOP_PRODUCTS",
      "productRules":  "rule incl price [0, 150.01]"
    }]
  }
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE