GuidesAPI Reference


This page details how to get started with Depict recommendations using our API

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:


Example request

// Function for getting a session ID. Explained below in this document.
function getSessionId(){var d;return(d=localStorage)._dep_id||(d._dep_id=(2e17*Math.random()).toString(36))};

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(),
                // 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 and user_id parameters.


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": "",
            "image_url": "",
            "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, and ideally when restarting their browser. If you don't have an ID you can use as the session ID, you can use this function.

* Stores a randomly generated number in localStorage or retrieves it when it already exists.
function getSessionId(){var d;return(d=localStorage)._dep_id||(d._dep_id=(2e17*Math.random()).toString(36))};

Other recommendation endpoints

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

Front page/user recommendations

What’s Next

Once you have recommendations on your site the next step is to setup the tracking for them using the Depict Performance Client (DPC)