The Recommendations API is designed to suggest similar items to a given item, based on user engagement behavior and item similarity. It can be used to provide similar or complementary product recommendations for your users. To get recommendations for a specific item, you need to use the /recommendations/document/{itemId} endpoint.

Get Recommendations for a Specific Item

API Reference: Recommendations

To get recommendations for a specific item, send an HTTP GET request to /recommendations/document/{itemId}?queryKey={queryKey}&limit=10 endpoint with the following parameters:

  • itemId - The ID of the item for which you want to get recommendations;
  • queryKey - The query key that will be used to load statistics, configurations and returned selectFields. Required;
  • limit - Limit number of returned recommended items. Optional. Defaults to 10, must not exceed 25.

Recommendations Request Example

GET /recommendations/document/25419?queryKey=my_query_key&limit=20
  "recommended": [
      "id": "84623",
      "name": "Recommended item 1"
      "id": "84624",
      "name": "Recommended item 2"
  "recommendFor": {
    "id": "25419",
    "name": "Original Item"

Response Description

  • recommended - An array of recommended items. Each item has properties defined in the given query's (one referenced with my_query_key) configuration's selectFields;

  • recommendFor - The original item (based on the given itemId parameter) reference with the same select fields as defined in the query's selectFields.

Possible Errors

  • 400 Bad Request - When the itemId or queryKey is invalid or missing. Check the error response for more information about the issue.

Note: The Recommendations API relies on analyzing user engagement behavior through the Events API. To ensure even more accurate product recommendations, make sure to report user engagement events appropriately, although this is not strictly required and without it, recommendations api will fallback to using static product data instead.

Product recommendations in dashboard

To preview product recommendations in your dashboard, go to Test Your Search page, type in any desired query and simply click on a product you want to get recommendations for.


The blue badges in front of recommended product ids indicate the relative relevance of a recommendation, that can fall in a range from 0 to 100.