This API enables you to retrieve item attribute details for catalog items using their unique item IDs. The attributes can include the title, price, category, link, image_link, and the respective creation date.
API Endpoint
Method: POST
https://api-0X.moengage.com/v1/catalog/{{Catalog_id}}/items/searchEach customer is hosted in a different data center. You can find your data center number (value of X) by checking the Data Center and API Endpoint Mapping Page.
Authentication
The API request is 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 bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}
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 |
|---|---|---|---|
| Content-Type | Required | {"Content-Type": "application/json"} | Set the Content-Type header to application/json. |
| Authorization | Required | {"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="} | Pass this authentication parameter, used for access control, in the request. For more information on generating the authentication header, refer to Authentication. |
| MOE-APPKEY | Required | {“MOE-APPKEY”: “Workspace ID”} |
This is the workspace ID (earlier APP ID) of your MoEngage workspace. Pass the MOE-APPKEY in the request. You can find your MoEngage Workspace ID in the MoEngage Dashboard at: Settings > Account > APIs > Workspace ID (earlier app id) For more information, refer to Authentication. |
Request Body
The request body consists of all items to be ingested, including item details with the mandatory attributes and other attributes defined in the attribute schema during catalog creation.
| Key | Required | Values | Description |
|---|---|---|---|
| items | Required | JSON Object |
This API accepts a list of unique IDs (strings) that represent the items you want to fetch. This field accepts a maximum of 50 item IDs per request. If the count exceeds this limit, the request results in an error. "items": [ "{{item_ID_1}}", "{{item_ID_2}}", "{{item_ID_3}}", ] Note: The request may fail if mandatory attributes are missing from the item configuration. |
Response
| Status | Key | Data Type | Description |
|---|---|---|---|
| Success | message | JSON Object |
The message provides a brief update on the status of the request. In the event of a successful request, the message lists both valid and invalid tagged items, with their respective descriptions. In the event of an unsuccessful request, the message displays the reason for the failure.
|
| Failure | error-code | String | Each error code is unique and serves as a shorthand representation for the type of error. They provide a quick reference that can be used to diagnose, troubleshoot, and address the problem based on a predefined set of error conditions. |
For more information, refer to the Error Messages section.
Response Codes
| Status Code | Request State | Description |
|---|---|---|
| 200 | Success | Items retrieved successfully. |
| 400 | Bad Request | Payload size validation failed or invalid request format. |
| 401 | Authentication Failure | Unauthorized request. |
| 403 | Forbidden | The request is not authorized. |
| 404 | Page not found | Catalog not found. |
| 413 | Request entity too large | The request body can be large in terms of size (bytes). |
| 429 | Too Many Requests | Too Many requests; there won't be any response body for this. |
Error Messages
| Status Code | Error code | Description |
|---|---|---|
| 400 | invalid-request | Item count must be greater than 0 and less than or equal to 50. |
| 401 | request-unauthenticated | Your request is unauthorized. Verify your credentials and try again. |
| 403 | request-denied | Your account does not have access to the Recommendations and Catalogs features. Contact the MoEngage team for assistance. |
| 404 | catalog-not-found | The Catalog for the provided catalog ID could not be found. Verify the ID and try again. |
| 413 | payload-size-exceeded | Your payload size exceeds the 5 MB limit. Reduce the payload size and try again. |
Rate Limit
With the current implementation of a platform-based rate limiter, we support the following:
- Request limit: 100/min OR 1000/hr. You can request up to 50 items per request.
- Payload size limit: 5 MB only if the Content-Length header is provided.
| info |
Information The limit is a COMBINED limit across all Catalog APIs for a specific user. |
Sample cURL Request
curl --location --globoff 'https://api-{{0X}}.moengage.com/v1/catalog/{{catalog_ID}}/items/search' \
--header 'MOE-APPKEY: {{DATA_APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic e3tEQVRBX0FQUF9JRH19Ont7REFUQV9BUElfS0VZfX0=' \
--data '{
"items": [
"P001",
"P002",
"P003",
"P004"
]
}'Sample Response
| info |
Information The status code 429 is returned if the rate limit is exceeded. The API does not return any content for this status code. |
{
"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": "invalid-request",
"message": "Item count should be greater than 0 and less than or equal to 50"
}
{
"error-code": "request-unauthenticated",
"message": "Your request is unauthorized. Please verify your credentials and try again."
}
{
"error-code": "request-denied",
"message": "Your account does not have access to the Recommendations and Catalogs features. Please contact the MoEngage team for further assistance."
}
{
"error-code": "catalog-not-found",
"message": "We could not find any Catalog for the provided catalog id. Please verify the ID and try again."
}
{
"error-code": "payload-size-exceeded",
"message": "Your payload size exceeds the 5MB 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.
Postman Collections
We have made it easy for you to test the APIs. Click here to view it in Postman.
FAQs
Each error code is a uniquely defined shorthand representation for the type of error, providing a quick reference that can be used to diagnose, troubleshoot, and address the problem based on a predefined set of error conditions.
No, the data type cannot be changed once an attribute has been defined in the catalog. You can add a new attribute to the catalog using the Add new catalog attribute API with a different data type as needed.