Recommendation API responses

The response depends on the type of recommendation and the configuration of the item feed.

Tip: When configuring the item feed, in the Response attributes section, add only the attributes that you plan to use.

Item recommendations

These recommendations offer items.

In an item recommendation response:

the data array lists items as objects.
itemId is always included in each item’s object. Adding more details can be enabled in the “Response attributes” settings of the item feed.
the extras object contains:
- Slots (if applicable) with the IDs of the items they include. The details of those items are in data.
- IDs of context items, if applicable.
- A correlationId used for identifying which events result from which request. This is used in recommendation statistics and in analytics.

To display the results, you need to get item details from data. If you use multiple slots, you can use the data from extras.slots to arrange the results in the customer’s view.

Response example:

{
    // an array of items in the recommendation:
    "data": [
        { // one item as an object
            "itemId": "0196818716fta", // unique ID of the item from the item feed

            // additional attributes from item feed configuration:
            "title": "Baseball cap", 
            // the `link` attribute is automatically enriched with campaign/request metadata for tracking in Analytics and Automation
            "link": "https://example.com/baseball-cap?snrai_campaign=DkhvrZoTKthD&snrai_id=75ea91a9-3a27-4dbf-addc-b7006cf70d52",
            "color": "red"
        },
        ... // more items from the recommendation:
        {
            ...
        },
        {
            ...
        }
    ],

    // other data:
    "extras": {
        "contextItems": null, // context items, if applicable
        "correlationId": "75ea91a9-3a27-4dbf-addc-b7006cf70d52", // unique ID of this recommendation request

        // items sorted into slots:
        "slots": [
            { // one slot as an object
                "id": 2, // ID of the slot
                // a list of items in this slot (only IDs): 
                "itemIds": [
                    "0196818716fta", // a single item ID
                    ...
                ],
                "name": "no shoes", // name of the slot
                "rows": null // not used in item recommendation campaigns
            },
            // more slots:
            {
                ...
            },
            {
                ...
            }
        ]
    }
}

Section page recommendations

This type of recommendation offers items sorted into sections. The sections are created by selecting an attribute. All items within one section will have the same attribute value.

To learn about creating section page recommendations, read Creating section page recommendations.

In a section page recommendation response:

the data array contains the details of all the items in the recommendation. It works the same as in item recommendations.
the extras objects contains slots. In each slot, the rows array is a list of sections (objects) with item IDs and the attribute value that is common for the items in that section.
The number of sections and items in each section is defined separately for each slot.

To display the items, you need to take the section data from extras.slots.rows and the item details from data. You can also use data from the metadata catalog, such as item descriptions or image URLs.

Response example:
In this example:

the campaign contains 1 slot.
the slot contains 2 sections.
each section contains 3 items.
the selected attribute for creating sections is color

{
    // an array of items in the recommendation:
    "data": [
        { // one item as an object
            "itemId": "0196818719002", // unique ID of the item from the item feed

            // additional attributes from item feed configuration:
            "title": "Baseball cap", 
            // the `link` attribute is automatically enriched with campaign/request metadata for tracking in Analytics and Automation
            "link": "https://example.com/baseball-cap?snrai_campaign=DkhvrZoTKthD&snrai_id=75ea91a9-3a27-4dbf-addc-b7006cf70d52",
        },
        ... // more items from the recommendation:
        {
            ...
        },
        {
            ...
        }
    // other data:
    ],
    "extras": {
        "contextItems": null, // context items, if applicable
        "correlationId": "75ea91a9-3a27-4dbf-addc-b7006cf70d52", // unique ID of this recommendation request

        // items sorted into slots and sections:
        "slots": [
            { // one slot as an object
                "id": 0, // ID of the slot
                "itemIds": null, // not used in section page recommendations
                "name": "red items", // name of the slot

                // sections of the recommendation:
                "rows": [
                    {
                        "attributeValue": "red", // the common value of the selected attribute (color)
                        "itemIds": [
                            "0196818719002", // a single item ID
                            "0196499574457",
                            "0196996669878"
                        ],
                        "metadata": {
                            "imageLink": "https://example.com/section-images/red.png",
                            "title": "Red items"
                        }
                    },
                    {
                        "attributeValue": "green",
                        "itemIds": [
                            "0195953880516",
                            "0196895673303",
                            "0886614236611"
                        ],
                        "metadata": {
                            "imageLink": "https://example.com/section-images/green.png",
                            "title": "Green items"
                        }
                    }
                ]
            }
        ]
    }
}

Attribute recommendations

Attribute recommendations are functionally similar to item recommendations. However, instead of merchandise, they return attributes of that merchandise.

To learn about creating attribute recommendations, see Creating attribute recommendations.

In an attribute recommendation response:

the data array includes the recommended attributes. By default, only the itemId (attribute name) is returned. If you want to use more attributes, such as a link to a page listing items with that attribute, you must configure a metadata catalog (see Creating attribute recommendations).
the extras objects contain slots. Each slot contains the IDs of the attributes it includes.

To recommend items, you can:

Use the metadata catalog to add links as parameters of the recommended attributes.
You can also include other metadata, such as images, titles, descriptions, and so on.
Use the links to redirect users to pages that show items with a given attribute.

Response example:

In this example:

the campaign has 2 slots.
both slots use the color attribute as Item attribute.

a metadata catalog is enabled for the recommendation and includes a url attribute for each attribute value.

{
    // an array of attribute values in the recommendation:
    "data": [
        {
            "itemId": "brown", // unique ID of the attribute value

            // additional data from the metadata catalog:
            "url": "https://example.com/items-by-color/brown",
            "imageUrl": "https://example.com/attribute-images/brown.png",
            "description": "Autumn colors for you"
        },
        {
            "itemId": "blonde",
            ...
        },
        {
            "itemId": "blue",
            ...
        },
        {
            "itemId": "orange",
            ...
        },
        {
            "itemId": "white",
            ...
        },
        {
            "itemId": "pink",
            ...
        }
    ],
    "extras": {
        "contextItems": null, // context items, if applicable
        "correlationId": "839f6ae5-af2f-4771-b501-ea609a8e2611", // unique ID of this recommendation request

        // attribute values sorted into slots:
        "slots": [
            {
                "id": 0, // ID of the slot
                "itemIds": [
                    "brown", // a single attribute value
                    "blonde",
                    "blue"
                ],
                "name": "Unnamed slot",
                "rows": null // not used in attribute recommendations
            },
            {
                "id": 1,
                "itemIds": [
                    "orange",
                    "white",
                    "pink"
                ],
                "name": "Unnamed slot",
                "rows": null
            }
        ]
    }
}

Recommendation API responses

Item recommendations

Section page recommendations

Attribute recommendations

We are sorry to hear that

Awesome!