Skip to main content
POST
/
recommendations
/
{recommendations_id}
/
items
Fetch Recommendation Results
curl --request POST \
  --url https://api-{dc}.moengage.com/v1/recommendations/{recommendations_id}/items \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'MOE-APPKEY: <moe-appkey>' \
  --header 'RECOMMENDATION-TYPE: <recommendation-type>' \
  --data '
{
  "user_id": "user123@example.com",
  "item_id": "product_sku_abc",
  "include_fields": [
    "title",
    "image_link",
    "price"
  ]
}
'
{
  "items": [
    {
      "item_id": "prod_xyz",
      "title": "Stylish Red Scarf",
      "link": "https://example.com/products/prod_xyz",
      "image_link": "https://example.com/images/prod_xyz.jpg",
      "price": 19.99
    }
  ]
}

​
Rate Limit

You can fetch 10,000 recommendations per minute.

Authorizations

​
Authorization
string
header
required

The API request will be authenticated through Basic Authentication.

It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the Authorization header.

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

  1. Navigate to Settings > Account > APIs.
  2. Username: Under Workspace ID, copy your username.
  3. Password: In the API keys section, copy the API key from the Campaign report / Business events / Custom templates / Catalog API tile.

Headers

​
MOE-APPKEY
string
required

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)

​
RECOMMENDATION-TYPE
enum<string>
required

It represents the type of recommendations from which the results are fetched.

Available options:
user_action,
item_attribute,
catalog_alert,
similar_item,
frequently_viewed_together,
frequently_bought_together,
trending_item,
user_personalization

Path Parameters

​
recommendations_id
string
required

This parameter indicates the unique identifier associated with the recommendation created in the recommendation module.

You can obtain the recommendation_id from the recommendation you created on the recommendation page.

Body

application/json
​
user_id
string
required

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
string | null

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
string[] | null

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.

Example:
["title", "price", "image_link"]

Response

Indicates that the request is successful and a recommendation is fetched.

​
items
object[]