Fetch Recommendations Results for a User

This API lets you fetch/retrieve the metadata results of any recommendations for a user based on their user ID and item ID.

API Endpoint

Method: POST

https://api-{{0X}}.moengage.com/v1/recommendations/{{recommendations_id}}/items

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Path Parameters

Key	Sample Values	Description
recommendations_id	a1b2c3...	This parameter indicates the recommendation ID. You can obtain the recommendation_id from the recommendation you created on the recommendation page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

You can obtain the username and password details from the MoEngage Dashboard.

Navigate to Settings > Account > APIs.
Copy the following details:
- Username: Under Workspace ID (earlier App ID), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Campaign report/Business events/Custom templates/Catalog API tile to copy the API key.
- Use these details to authenticate the API requests.

Request Headers

Key	Required	Sample Values	Description
MOE-APPKEY	Required	{“MOE-APPKEY”: “Workspace ID”}	This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage Dashboard: Settings > Account > APIs > Workspace ID (earlier app id) For more information, refer to Authentication.
RECOMMENDATION-TYPE	Required	user_action item_attribute similar_item frequently_viewed_together frequently_bought_together trending_item user_personalization	It represents the type of recommendations from which the results are fetched.
Content-Type	Optional	{"Content-Type": "application/json"}	Set the Content-Type header to application/json.
Authorization	Required	{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}	This authentication parameter, used for access control, must be passed in the request. For more information on generating the authentication header, refer to Authentication.

Request Body

Key

Required

Values

Description

user_id

Required

String

A user ID is a unique identifier that represents a user. You can obtain the user_id from the user info page. For more information, refer to User Identity Management.

item_id

Optional

String

An item_id is a unique identifier assigned to each item in the catalog.

If the RECOMMENDATION-TYPE is any of the similar_item, frequently_viewed_together, or frequently_bought_together, you must provide the item_id.

This item_id acts as the anchor to serve recommended items based on the RECOMMENDATION-TYPE.

We expect the user's most recently interacted item_id to serve contextually recommended items.

include_fields

Optional

Array of strings

You can define the attributes of items you require from the catalog in the recommendation response. For example, title, price, link, image_link, and so on.

If the attributes above are not defined, all item attributes in the catalog will be included in the response. The response size may increase depending on the number of attributes in the catalog. Therefore, it is recommended that only the necessary attributes be specified.

Response

Status	Key	Data Type	Description
Success	items	JSON Object	This status indicates the request has been processed successfully without errors. For more information, refer to Items.
Failure	error-code	string	Each error code is unique and serves as a shorthand representation for the type of error. It provides a quick reference that can be used to diagnose and troubleshoot the problem based on a predefined set of error conditions.
Failure	message	string	With the error code, a detailed message is also provided in the response describing the specifics of the request failure and the nature of the error.

Refer to the Sample Response section for examples

Items

The items JSON object contains the key-value pairs of all the requested attributes. For example:

Metrics	Data Type	Description
item_id	String	This field shows the ID of the item.
image_link	String	This field shows a link to the image.
link	String	This field shows a link to the item.
title	String	This field shows the title of the item.

Response Codes

Status Code	Request State	Description
200	Success	Indicates that the request is successful and a recommendation is fetched.
400	Bad request	Possible issues include a recommendation, the user does not exist, or the wrong format provided.
401	Unauthenticated	Your request is unauthorized. Verify your credentials and try again.
413	Request entity too large	The request body can be large in terms of size (bytes) or length of items.
429	Too Many Requests	There won't be any response body for this request.
500	Internal server error	This response is returned when the system runs into an unexpected error.

Rate Limit

You can fetch 10,000 recommendations per minute.

Note: The maximum size of the payload is 1 MB.

Sample cURL Request

curl --location 'https://api-0X.moengage.com/v1/recommendations/{recommendation_id}/items' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'RECOMMENDATION-TYPE: frequently_viewed_together' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data '{
  "user_id": "{{user_id}}",
  "item_id": "Y_1",
  "include_fields": [
    "image_link"
  ]
}'

Sample Response

{
    "items": [
        {
            "catalog_id": {{catalog_id}},
            "feed_id": "{{feed_id}}",
            "title": "string",
            "description": "string",
            "link": "https://link.in/",
            "image_link": "https://link.in/",
            "price_currency": "USD",
            "creation_date": "2024-05-10T07:03:00.180000",
            "last_updated": "2024-05-10T07:03:00.180000",
            "product_id": "string",
            "price": double,
            "date": "2022-04-05T00:00:00"
        }
    ]
}

{
  "error-code": "recommendation does not exist",
  "message": "Recommendation does not exist or archived. Please check recommendation_id."
}

{
  "error-code": "request-unauthenticated",
  "message": "Your request is unauthorized. Please verify your credentials and try again."
}

{
  "error-code": "payload-size-exceeded",
  "message": "Your payload size exceeds the 1MB limit. Please reduce the payload size and try again."
}

The following headers are returned in case of rate-limit breach:

x-ratelimit-limit (integer)- The maximum number of requests that the consumer is permitted to make in a given time window.

x-ratelimit-remaining (integer)- The number of requests remaining in the current rate limit window.

x-ratelimit-reset (integer)- The time at which the current rate limit window resets in UTC epoch seconds.

{
  "error-code": "unexpected-error",
  "message": "Something went wrong with your request. Please contact the MoEngage team for further assistance."
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.