Once Depict has configured the recommendations and they are ready to be delivered, there are two things that needs to be done to actually provide the recommendations on your website:

  • Request recommendations to display on your website, most commonly as Product Cards
  • Send events for tracking user interaction with the recommendations.

For the complete API specification, see API Reference.

Requesting recommendations

There are multiple endpoints available for different kinds of recommendations. We begin by showing how you get recommendations for a given Product ID, which is what you do when, for example, displaying recommendations on a product’s product page.

Get recommendations for a single product

For displaying recommendations on a product’s product page use following endpoint:

POST https://api.depict.ai/v2/recommend/products/product

Example request

async function getRecommendationsForProduct(productId) {
  const response = await fetch(
      method: "POST",
      data: JSON.stringify({
        tenant: "myexamplestore",
        market: "se",
        type: "similar",
        product_id: productId,
        session_id: getSessionId(), // See the "Session ID and User ID" section below
        // user_id: getUserId() // Optional
  // handle the response

In the request, specify the product_id for the product you want the recommendations to be based on, as well as the type of recommendations to generate.
The available types depend on what Depict has configured for you. Common examples include “similar”, “cross_sell”, and “checkout”.

You must also include your store’s unique identifier in the tenant field and the market name as market.

In order to identify the user interacting with the recommendations you must send the session_id parameter, and optionally user_id when available.


The response contains a list of recommended products with everything you need to display the product cards.

💡 We can help you extend the fields that are returned if there is anything specific you need. For example, you may want the sustainability value as a field to show each recommended product’s sustainability score. Just make sure this field is available or can be computed from the data you have provided us.

Example response

    "displays": [
            "main_product_id": "234234",
            "product_id": "45234234",
            "title": "A very nice product",
            "original_price": 999,
            "sale_price": 899,
            "page_url": "https://www.myexamplestore.com/45234234",
            "image_url": "https://www.myexamplestore.com/45234234/image.jpg",
            "sustainability_value": 5,
            "recommendation_id": "ee3652eb-a459-459c-aaa6-52e2c0e5695a"

Session ID and User ID

We require you to send the session and user IDs in the request. The ids are used to track customer interactions with the recommendations as well as improving the recommendations.

The User ID is used to identify a logged-in user. You can use anything that identifies a logged-in user here. Common examples include using the username and user ID. Leave this field unset or as null/undefined if you don’t have an ID available.

The session ID is used to identify any user, regardless of whether the user is logged in or not. The session ID should always be present in requests. You can use anything that identifies a user and is persistent when the user navigates around the page, including the checkout and order confirmation pages. Ideally the session should also persist after a browser restart.

Other recommendation endpoints

Getting recommendations for multiple products (e.g. checkout recommendations)

Front page/user recommendations