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.

For more information on how to get up and running with the API library, see the 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 recommendation lists on pages in the Elevate application , 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 recommendations

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 query parameter. It uses previously notified add-to-cart events to know what is in the cart.

Example

REST API
JS Library

Contents of request-body.json

{
  "recommendationLists": [
    {
      "id": "ATC-1",
      "algorithm": "ADD_TO_CART_RECS"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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 query parameter.

Example

REST API
JS Library

Contents of request-body.json

{
  "productGroup": {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "ALTERNATIVES"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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

REST API
JS Library

Contents of request-body.json

{
  "recommendationLists": [
    {
      "id": "CART-1",
      "algorithm": "CART"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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

REST API
JS Library

Contents of request-body.json

{
  "recommendationLists": [
    {
      "id": "FAV-1",
      "algorithm": "FAVORITES"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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. It 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 catalog import, using the series attribute. Series are global for the entire product catalog, so if two brands have a series with the same name, 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, such as “Billy Ikea” for the series ID and “Billy” for the series name.

Example

REST API
JS Library

Contents of request-body.json

{
  "productGroup": {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "MORE_FROM_SERIES"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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 products

The Newest products recommendation is suitable to use on a landing page dedicated to new arrivals. It returns products sorted by newness. Elevate determines newness based on the releaseDate attribute supplied in the catalog import.

Example

REST API
JS Library

Contents of request-body.json

{
  "recommendationLists": [
    {
      "id": "NEW-1",
      "algorithm": "NEWEST_PRODUCTS"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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

REST API
JS Library

Contents of request-body.json

{
  "recommendationLists": [
    {
      "id": "PERSONAL-1",
      "algorithm": "PERSONAL"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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' }
    ]
  }
);

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 a lens, a battery, and a cable. The product currently viewed is declared in the productKey query parameter. The products that go together must be specified in the catalog import using the styleWith attribute.

Example

REST API
JS Library

Contents of request-body.json

{
  "productGroup": {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "STYLE_WITH"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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

REST API
JS Library

Contents of request-body.json

{
  "recommendationLists": [
    {
      "id": "TOP-1",
      "algorithm": "TOP_PRODUCTS"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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

REST API
JS Library

Contents of request-body.json

{
  "productGroup": {
    "include": true
  },
  "recommendationLists": [
    {
      "id": "PDP-1",
      "algorithm": "UPSELL"
    }
  ]
}

curl -X POST \
"https://{cluster-id}.elevate-api.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 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 the TOP_PRODUCTS or NEWEST_PRODUCTS recommendation, the recommendation can be limited to a 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]"
  }]
}

Overview

Catalog modeling

Feature concepts

Search and facets

Recommendations

Pages and navigation

Storefront responses

Operations

Overview

Add-to-cart recommendations

Example

Alternatives

Example

Cart

Example

Favorite

Example

More from series

Example

Newest products

Example

Personal

Example

Recently viewed

Example

Style with

Example

Top products

Example

Upsell

Example

Tips

Combine recommendations

Targeted recommendations

​Overview

​Add-to-cart recommendations

​Example

​Alternatives

​Example

​Cart

​Example

​Favorite

​Example

​More from series

​Example

​Newest products

​Example

​Personal

​Example

​Recently viewed

​Example

​Style with

​Example

​Top products

​Example

​Upsell

​Example

​Tips

​Combine recommendations

​Targeted recommendations

Overview

Add-to-cart recommendations

Example

Alternatives

Example

Cart

Example

Favorite

Example

More from series

Example

Newest products

Example

Personal

Example

Recently viewed

Example

Style with

Example

Top products

Example

Upsell

Example

Tips

Combine recommendations

Targeted recommendations