Called via a POST request:

POST https://recs.qubit.com/vc/recommend/2.1/<tracking_id>?strategy=<strategy_name>&n=<no_of_recs_to_return>&locale=<language-currency>

Before using the Recommendations API, you will require the following unique values:

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/demo_uk_prod?strategy=popular&n=10&locale=en-gb-GBP&experienceId=20351\
      -H 'content-type: application/json' \
      -d '{"h": ["all"]}'

Where:

• demo_uk_prod is the Qubit tracking Id for the property the request is made from. Your CSM at Qubit will provide this.
• strategy is one of Qubit's recommendations strategies. See Strategies for more information. If not specified, defaults to popular
• n is the number of products to recommend. If not specified, defaults to 10. Maximum is 50
• locale see Locales. If not specified, defaults to the most common language/currency combination seen in your product catalog
• experienceId is the Id of a recommendations experience containing promotion or blacklisting rules you want to pass into your request
• h is an optional parameter to define the history or seed to generate recommendations for. Can accept an array of product Ids/SKUs. See The recommendation seed for details and examples

WARNING: Recommendations are typically generated using product Id. If you wish to use SKU instead, you will need to inform Qubit during the onboarding process.

INFO: Recommendations are generated using the products from across your entire product catalog and all provided locales. This means, for example, if you are using the popular strategy strategy=popular, we will generate a list of product Ids for popular products from all locales. The locale passed in your request is then used to return specific product information (name, description, price, etc).

The Recommendations API will always generate a response with HTTP status 200 for any responses it has control over.

TIP: Always check the status field to ensure that the response has been successful.

The response body will be a JSON object containing the following fields.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
  items: [
      {
        id: '5637911031',
        weight: 0.07154133712308453,
        details: {
          category: 'Craft Essentials',
          unit_sale_price: 1.5,
          subcategory: 'Craft Paint',
          url: 'http://www.crafters.co.uk/deco-art-crafters-acrylic-white-2oz/563791-1031',
          sku_code: '5637911031',
          unit_price: 1.5,
          name: 'Deco art Crafters Acrylic White 2oz',
          currency: 'GBP',
          image_url: 'http://www.crafters.co.uk/supplyimages/563791_1031_1_170.jpg',
          stock: 3,
          id: '563791',
          description: 'Deco art Crafters Acrylic White 2oz'
        }
      }
    ]
}

If either the strategy or tracking Id is invalid, we will return a response with status code 200, but with 0 results:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
  items: []
}

If you make an error passing in the tracking Id for your property, we will return a response with status code 404:

HTTP/1.1 404 OK
Content-Type: application/json;charset=utf-8
{
"status": 404,
"message": "Requested URL /vc/recommend/2.1/ not found"
}

To deliver recommendations, we offer the possibility to use one of our own natively-developed strategies or one of Google's Recommendations AI strategies.

Refer to the following tables for details of each of Qubit's strategies. We've also included the name of each strategy as it displays in the Merchandising Hub:

You can read more about each of Qubit's strategies in Qubit's plug and play strategies.

You can read more about how Qubit has teamed up with Google to deliver the most effective product recommendations available today on our website.

Refer to the following table for guidance on the best place to use each strategy:

Qubit's engagement, upsell, conversion, and trending strategies are referred to as composite strategies because they are composed of a principal strategy and one or more additional strategies that function as fallbacks.

The fallback logic ensures that if the principal strategy for the given seed doesn't return the requested number of recommendations, the request is fulfilled by falling back to the next strategy.

For example, if fifteen results are requested, and the first strategy returns ten results, we would fetch the remaining five from the first fallback strategy, and so on.

Refer to the following tables for details of the fallbacks for our composite strategies:

• cf_viewed - uses collaborative filtering based on views of product items
• pllr - uses log-likelihood ratio to surface product connections based on views

• cf_bought - uses collaborative filtering based on purchases of product items
• pllr_bought - uses log-likelihood ratio to surface product connections based on purchases

• pllr_viewed_bought - uses log-likelihood ratio to surface product connections based on a combination of views and purchases

For a discussion of the differences between collaborative filtering and log-likelihood ratio, refer to What's the difference between collaborative filtering and log-likelihood ratio?

Unlike composite strategies, by default, non-composite strategies do not operate with fallbacks:

• popular - recommends most viewed/bought products across a site over the last 30 days
• new - recommends products recently added to a product catalog
• pllr_bought_next - recommends products purchased after purchasing the seeded product

You can add fallbacks of your own to ensure that recommendations are delivered if the chosen strategy doesn't deliver the required number of products. Let's look at an example:

https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=pllr,pllr_bought_next&seed=4000135NI_1100&n=100&locale=en-GBP

Where:

• strategy is a comma-separated list of strategies, with the principal strategy in position one and any fallbacks you want to use after that, for example, pllr,pllr_bought
• seed is a product Id, for example, 4000135NI_1100
• n is the number of recommendations to return

WARNING: Although the API does not enforce limits, there is no practical reason to use more than two to three fallbacks.

Qubit's trending strategy considers views over time to determine which products are genuinely trending. For example, if a product is viewed 100 times every day, its popularity is not changing over time, and it is therefore not trending. If a product was viewed 5 times day 1, 20 times day 2, and 50 times day 3, its popularity is changing over time. We consider this product to be trending.

We no longer support the following strategies and recommend that they are no longer used:

In this section, we will take a look at how you can use strategies to deliver recommendations.

Recommend products viewed together with a specific product, returning 5 product recommendations:

• strategy=engagement
• W000277351
• n=5

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=engagement&n=5&locale=fr-EUR' \
      -H 'content-type: application/json' \
      -d '{"h": ["W000277351"]}'

Recommend products bought together with a specific product, returning 10 product recommendations:

• strategy=upsell
• W000277351
• n=10

curl -X POST \
     'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=upsell&n=10&locale=en-us-USD' \
     -H 'content-type: application/json' \
     -d '{"h": ["W000277351"]}'

Recommend the most popular products, returning 5 product recommendations:

• strategy=popular
• all
• n=5

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=popular&n=5&locale=en-GBP' \
      -H 'content-type: application/json' \
      -d '{"h": ["all"]}'

Recommend the most popular products within the provided seed category, returning 5 product recommendations.

Example 1:

• strategy=popular
• {"type": "c", "id": "handbags"}
• n=5

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=popular&n=5&locale=en-GBP' \
      -H 'content-type: application/json' \
      -d '{"h": [{"type": "c", "id": "handbags"}]}'

Example 2:

• strategy=popular
• {"type": "c", "id": "Home > Shoes"}
• n=10

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=popular&n=10&locale=en-GBP' \
      -H 'content-type: application/json' \
      -d '{"h": [{"type": "c", "id": "Home > Shoes"}]}'

WARNING: In "type": "c", the value "c" is case sensitive and must be lower-case. In "id": "category", the category name must exactly match the value in the QP field product.categories.

Recommend products bought next after purchasing the seeded product, returning 3 product recommendations:

• strategy=pllr_bought_next
• W000277351
• n=3

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=pllr_bought_next&n=3&locale=en-GBP' \
      -H 'content-type: application/json' \
      -d '{"h": ["W000277351"]}'

The seed parameter defines the products and product categories to generate recommendations for. If there is sufficient data about the provided seed, for example, products viewed or bought together with a product, we will return recommendations.

By adding or omitting a seed, you can use each strategy in the manner best suited to where you are adding the recommendations carousel.

TIP: Although there are places where a single product Id should be used as the seed, for example, on product detail pages, where possible, we recommend using an array of product Ids as the seed to guarantee a richer, aggregated set of recommendations. This is especially true for a homepage or a search page that hasn't returned results from a product search.

WARNING: Except for the strategy popular, the recommendation seed will always be a product Id-or SKU if specified during onboarding.

{
	"h": ["W000277351"]
}

Where:

• h is an optional parameter to define the history or seed to generate recommendations for

A seed is considered contextual if the value is a product Id, an array of Ids, or a category Id (only for popular):

{
  "h": ["W000277351","W000277352","W000277353"]
}

And generic if the value is all:

{
  "h": ["all"]
}

A contextual seed is obtained by passing specific product Ids or, and only for popular, a category Id, to generate recommendations.

On product detail pages, you might generate recommendation for the product being viewed by passing its product Id:

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_property?strategy=engagement&n=15&locale=en-us-USD' \
      -H 'content-type: application/json' \
      -d '{"h": ["W000277351"]}'

On basket pages, you might generate recommendations for all of the products present in the shopper's basket by passing an array of product Ids:

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_property?strategy=conversion&n=5&locale=en-us-USD' \
      -H 'content-type: application/json' \
      -d '{"h": ["W000277351","W000277352","W000277353"]}'

TIP: By sending multiple product Ids, the endpoint will aggregate the results and return the top sorted recommendations.

On the other hand, a generic seed is obtained by seeding the recommendation with all.

For example, on a homepage, it may make more sense to recommend trending products from across your product inventory:

curl -X POST \
      'https://recs.qubit.com/vc/recommend/2.1/example_property?strategy=trending&n=10&locale=fr-EUR' \
      -H 'content-type: application/json' \
      -d '{"h": ["all"]}'

Qubit offers the possibility to refine recommendations through the application of rules. These can be defined globally for your property or for one or more experiences in the Recommendations page.

For certain use cases, for example, where you wish to heavily promote a product by applying a higher weight than can be defined when defining rules in the platform, it might be appropriate to use rules on a per-request basis.

We refer to these rules as per-request filters because they are restricted to the API request containing the filter and are then discarded.

When calling the Recommendations API, per-request filters are added to any global rules defined in the platform and any experience-specific rules (if passed in your request). Observe the following points closely:

• Per-request filters are restricted to the request containing them
• Filters are added to global rules and any experience-specific rules (but only if you pass the experienceId in your request) but do not override them
• The application of filters in requests containing multiple seeds is impractical. For this reason, filters are only applied to the first seed within the request

For information about adding global rules for blacklisting and promoting products in the Qubit platform, see Available Rules.

Let's look at a simple per-request filter that includes blacklist and promotion elements. We have not passed an experienceId in the request, so the rules will only be added to globally-defined rules:

curl -X POST \
  'http://localhost:6662/vc/recommend/2.1/example_property?strategy=popular&n=10&locale=en-us-USD' \
  -H 'Content-Type: application/json' \
  -d '{
   "h":["all"],
   "rules":[
      {
         "name":"Blacklist low price",
         "condition":{ "<=":[ 0, { "var":"rec.unit_price" }, 30 ] },
         "factor":0
      },
      {
         "name":"Promote Shirts-Tops",
         "condition":{ "in":[ "Shirts-Tops", { "var":"rec.categories" } ] },
         "factor":2
      }
   ]
  }'

Where:

• name is the filter name, used for information purposes only
• condition is the logic used to filter products - written in JsonLogic
• factor determines whether the filtered products are blacklisted "factor":0, or promoted e.g. "factor":1, "factor":2, etc if condition evaluates as true

Looking at the previous example, the first rule blacklists products with a unit price less than or equal to 30. The second rule promotes products in the Shirts-Tops product category by a factor of 200. It is worth remembering that a promotion rule added in the platform will apply a factor of 2.

To assist you in building filters, the JsonLogic site includes a playground for testing condition logic. To use the site, copy the entire condition value into Rule field:

{
    "seed": <seed product details>,
    "rec": <recommended product details>
}

For a list of supported operations, see Operations.

Please take note of the following points:

• Weight determines the position in the recommendations carousel. The higher the weight, the higher the position
• Where applied, factors impact the weight applied to a product from a particular strategy weight x factor:
  • factor=0 (blacklisting) -> last position in carousel and filtered from it
  • factor=1 -> no effect
  • factor=>1 (promotion) -> higher position in the carousel

You can also use regex to define filters using the match operator. If you want to use multiple regexes, then use match_some instead of match:

Example - match:

{
    "name": "Blacklist product ids starting with RX_",
    "factor": 0,
    "condition": {
        "match": [{"var": "rec.id"}, "^RX_.*$"]
    }
}

Example - match_some:

{
    "name": "Blacklist product ids containing test or starting with RX_",
    "factor": 0,
    "condition": {
        "match_some": [{"var": "rec.id"},["^RX_.*$", ".*test.*"]]
    }
}

Refer to the following examples that show how you can use per-filters.

Promote products by a factor of 2 belonging to a specific brand in the product categories shoes and pants:

{
  "name":   "Brand promotion",
  "condition": { "and": [
  {"or": [
    { "in": [ "Shoes": { "var": "rec.categories" }]},
    {"in": ["pants": { "var": "rec.categories" }]}
  ]},
  { "==": [ { "var": "rec.brand" }, "adidas" ] }
  ]},
  "factor": 2
}

Only recommend products that are the same size as the returned seed product:

{
  "name":   "same size recommendations",
  "condition": { "!=": [ { "var": "seed.size" }, { "var": "rec.size" } ] },
  "factor": 0
}

Don't recommend products that are the same size as the returned seed product:

{
  "name":   "different size recommendations",
  "condition": { "==": [ { "var": "seed.size" }, { "var": "rec.size" } ] },
  "factor": 0
}

Don't recommend products with less than ten items in stock:

{
  "name":   "low stock products filter ",
  "condition": { "<": [ { "var": "rec.stock" }, 10 ] },
  "factor": 0
}

Don't recommend products with a price between 11 and 99 USD:

{
  "name":   "filter products with 10 < price < 100 USD",
  "condition": {"and": [
    { "<": [ 10, { "var": "rec.price" }, 100 ] },
    { "==": [ { "var": "rec.currency" }, "USD" ] }
  ]},
  "factor": 0
}

Don't recommend products that have a price higher than the returned product seed:

{
  "name":   "higher price recommendations",
  "condition": { ">": [ { "var": "rec.price" }, { "var": "seed.price" } ] },
  "factor": 0
}

Only recommend products from the category blow dryers when viewing combs:

{
  "name": "only sell blow dryer with a comb",
  "condition": { "and": [
    { "in": [ "combs", { "var": "rec.categories" }]}
    { "!": {"in": [ "blow dryer", { "var": "seed.categories" }]}}
  ]},
  "factor": 0
}

Recommend blow dryers when viewing combs by a factor of 2:

{
  "name": "promote blow dryers when viewing combs",
  "condition": {"and": [
    {"in": ["combs", { "var": "rec.categories" }]}
    {"in": ["blow dryer", { "var": "seed.categories"}]}    
  ]},
  "factor": 2
}

In this real-life example, we demonstrate the possibilities when using per-request filters to customize the recommendation seed fully:

{
  "rules": [
    {
      "name": "low stock config",
      "condition": { "<": [ { "var": "rec.stock" }, 10 ] },
      "factor": 0
    },
    {
      "name": "low price config",
      "condition": { "and": [
        { "<": [ { "var": "rec.price" }, 30 ] },
        { "==": [ { "var": "rec.currency" }, "GBP" ] }
      ]},
      "factor": 0
    },
    {
      "name": "blacklist config",
      "condition": { "or": [
        { "in": [ "Adult", { "var": "rec.categories" }] },
        {"match_some": [{"var":"rec.description"},["^Sample*", "*Tester.$"]]},
        { "==": [ { "var": "rec.is_clearance" }, true ] },
        { "in": [
          { "var": "rec.sku_id" },
          [ "23757604", "23757639", ... ]
        ]}
      ]},
      "factor": 0
    },
    {
      "name": "promote products",
      "condition": { "==": [ { "var": "rec.id" }, "24004952" ] },
      "factor": 2
    }
  ]
}

You can output the rules object in the response by appending a query parameter debug=True to the API request. You can view this object to determine which rules, if any, are being used to filter a recommendation:

https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=engagement&n=5&debug=True

In the following example, we see that a recommendation was filtered using a rule called Blacklist - out of stock:

You can retrieve recommendations by passing through the Experience API (options). Recommendations will be returned based on the defaults listed in the Configuration section below.

const recommendations = require('@qubit/recommendations')(options)

recommendations.get().then((recs) => {
  console.log(recs)
})

If you are making only one type of recommendation request, where the strategy and number of products you wish to use will be the same, you can define this upfront by providing your own configuration.

You can override any key shown in Configuration section below.

const productId = options.state.get('productId')

const recommendations = require('@qubit/recommendations')(options, {
  strategy: 'pp1',
  limit: 20,
  seed: productId
})

recommendations.get().then((recs) => {
  console.log(recs)
})

Sometimes, we're required to implement more a customized recommendations call. To do this, we specify our configuration at the time of making the request. This approach is useful if you need to make more than one request on a pageview.

Configuration passed to get overrides any configuration you pass when initializing the module, such as in the Standard example above.

Any keys you leave out will fallback to the configuration passed when initialized or the defaults described in Configuration if no initial configuration was used.

const recommendations = require('@qubit/recommendations')(options)

recommendations.get({
  strategy: 'popular',
  limit: 30,
  seed: [{ category: 'jeans' },{ category: 'blazers' }],
  rules: [{
    condition: {
      '!==': [{
        var: 'rec.custom_field'
      }, {
        var: 'seed.custom_field'
      }]
    },
    factor: 0
  }]
}).then((recs) => {
  console.log(recs)
})

We will return id, weight, and strategy for every recommendation, so if you're looping through the API response to render recommendations, this data will be immediately available to make the call.

Here's an example of how you might choose to emit shown and clicked events:

const recommendations = require('@qubit/recommendations')(options)

recommendations.get().then((recs) => {
  const $recs = recs.map((product, i) => {
    const { details } = product

    recommendations.shown(product)

    return $(`
      <div class="t001-rec">
        <a href="${details.url}">
          <img class="t001-img" src="${details.image_url}" />
          <div class="t001-name">${details.name}</div>
          <div class="t001-price">${details.unit_sale_price}</div>
        </a>
      </div>
    `).click(() => {
      recommendations.clicked(_.assign({ position: i + 1 }, product))
    })
  })

  $(`.product-details`).append($recs)
}).catch(err => {
  console.log(err)
})

INFO: If you include this package in a Qubit experience, the get call should take place in triggers.js, so you can verify a response before activating.

You can override as little or as much of the configuration shown in the examples above.

• type - String
• default - popular
• options - engagement, upsell, conversion, popular, trending, new, pllr_bought_next

• type - String
• default - most common language/currency combination seen in your product catalog

• type - Number
• default - 10

A number specifying the number of recommendations you wish to return. The API might respond with fewer recommendations than the specified limit, in which case, depending on the strategy used, we will fall back to a secondary strategy. See Composite strategies for more information.

If no recommendations are generated from the seed, the promise will be rejected. See timeout for details of how to handle errors.

• type - String or array
• default - all

As mentioned above, you can seed recommendations with product Ids/SKUs.

Product Ids/SKUs can be passed as a string. Place within an array to combine:

[{"W000277351","W000277352","W000277353"}]

• type - Array
• default - none

See Per-request filters for details.

• type - Number
• default - 0

The default of 0 milliseconds means no timeout will occur. Should you wish to cancel the loading of recommendations after a set period, pass the timeout key and attach a catch block to perform an alternate operation:

const recommendations = require('@qubit/recommendations')(options, {
  timeout: 3000, // 3 sec
})

recommendations.get().then((recs) => {
  console.log(recs)
}).catch((e) => {
  // perform alternate action
})

• type - String
• default - options.meta.trackingId

Should you wish to request recommendations for a different property, perhaps to build on a staging environment, but would like to request production recommendations, this can be set here.

• type - String
• default - options.meta.visitorId

This package assumes usage within a Qubit experience. If using elsewhere, you can specify how the Qubit Visitor Id should be found, typically via the _qubitTracker cookie.

• type - String
• default - https://recs.qubit.com/vc/recommend/2.1/

The Recommendations API endpoint.

To enable the metrics and reporting features within the Qubit platform for a recommendations experience, implement the following events:

• When a recommendation is shown/rendered onto the page:

recommendations.shown({
  id: 'ABC123',
  weight: '0.9',
  strategy: 'pop'
})

• When a recommendation is clicked:

recommendations.clicked({
  id: 'ABC123',
  weight: '0.9',
  strategy: 'pop',
  position: 1
})

Refer to Product recommendations for details of which events need to be emitted to deliver product recommendations.

We recommend also referring to our Events page to determine which events to emit.