Ingest Items into the Catalog

You can use this API to ingest items into an existing catalog as long as the attributes provided during ingestion match the attributes provided during catalog creation.

API Endpoint

POST https://api-0X.moengage.com/v1/catalog/{{Catalog_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.

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 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=="}

This authentication parameter, used for access control, must be passed in the request. To generate 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. 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.

Request Body

The request body consists of all the 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

MoEngage accepts the following mandatory attributes with every Catalog:

title - name of the item (string)
link - weblink of the item (string)
id - unique ID of that represent this item item (string)
image_link - image source link of this item (string)

This field accepts a minimum of 1 and a maximum of 50 attributes including the 4 mandatory attributes.

Response

Key

Data Type

Description

message

JSON Object

The message briefly describes the request status. In case of a successful request, the message will list the valid and invalid tagged items with their respective descriptions. In case of an unsuccessful request, the message displays the reason for failure.

valid: If the item is valid, the request is considered to be successful, and the API returns a valid count and ingests the item.
- count - The count of added items will be shown under this key.
invalid: For each invalid item, the API returns the reason for the request's failure. The error object contains the following fields:
- count - The count of items that failed to be added will be shown under this key.
- details - A JSON object shows deeper details on the type of errors that occurred while adding these items to the catalog. The details key consists of an errorId, error message, count of failed items, and the list of failed item ids per error type.

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 info, refer to the Error Messages section.

Response Codes

Status Code	Request State	Description
200	Success	Items ingestion was successful.
400	Bad Request	Payload size validation failed.
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) or length of items.
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	Something went wrong with your request. Please contact the MoEngage team for further assistance.
401	request-unauthenticated	Your request is unauthorized. Please verify your credentials and try again.
403	request-denied	Your account does not have access to the Catalog APIs. Please contact the MoEngage team for further assistance.
404	catalog-not-found	We could not find any API based catalog for the provided catalog id. Please verify the ID and try again.
413	payload-size-exceeded	Your payload size exceeds the 5MB limit. Please reduce the payload size and try again.

There could be instances where your requests with multiple items are processed successfully, but some of the items might not successfully get added to the catalog because of the following reasons:

Error Id	Description
missing-mandatory-attributes	Your must include mandatory attributes: id, title, link, and image_link with string data type and try again.
duplicate-item-ids	Item ids within a catalog must be unique. Please ensure your request contains unique item ids for the given catalog and try again.
invalid-item-attribute	The provided item attribute is not part of the defined catalog schema. Please check your catalog schema and try again.
invalid-datatype-attribute	We could not find any API based catalog for the provided catalog id. Please verify the ID 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.
Payload size limit - 5MB only when Content-Length header is provided.

info	Information The limit is a COMBINED limit across all the Catalog APIs for a given user.

Sample cURL Request

curl --location --globoff 'https://api-{{0X}}.moengage.com/v1/catalog/{{catalog_ID}}/items' \
--header 'MOE-APPKEY: {{DATA_APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic e3tEQVRBX0FQUF9JRH19Ont7REFUQV9BUElfS0VZfX0=' \
--data '{
    "items": [
        {
            "id": "{{item_ID}}",
            "title": "{{title}}",
            "link": "{{link}}",
            "image_link": "{{image_link}}"
        },
        
        {
            "id": "Cathe",
            "title": "Pearl Jam Twenty",
            "link": "https://google.co.jp/consequat/lectus/in/est.json?eros=lacinia&viverra=aenean",
            "image_link": "http://dummyimage.com/105x100.png/ff4444/ffffff"
        }
    ]
}'

Sample Response

info	Information The status code 429 will be returned if the rate limit is exceeded. The API does not return any content for this status code.

{
  "message": {
    "valid": {
      "count": 1
    },
    "invalid": {
      "count": 8,
      "details": [
        {
          "error-id": "duplicate-item-ids",
          "message": "Item ids within a catalog must be unique. Please ensure your request contains unique item ids for the given catalog and try again.",
          "count": 1,
          "document_ids": [
            "567890"
          ]
        },
        {
          "error-id": "missing-mandatory-attributes",
          "message": "Your must include mandatory attributes: id, title, link, and image_link with string data type and try again.",
          "count": 1,
          "document_ids": [
            "567890"
          ]
        },
        {
          "error-id": "items-missing-ids",
          "message": "There are items that do not have item IDs. Check that each item has an item ID.",
          "count": 1,
          "document_ids": [
            ""
          ]
        },
        {
          "error-id": "invalid-datatype-attribute",
          "message": "The provided item attribute {attribute name} with value {attribute value} can't be converted to the data type {data type} as defined in the catalog schema.",
          "count": 1,
          "document_ids": [
            "7523675"
          ]
        },
        {
          "error-id": "invalid-item-attribute",
          "message": "The provided item attribute is not part of the defined catalog schema. Please check your catalog schema and try again. Undefined attributes: shipping_price",
          "count": 2,
          "document_ids": [
            "312",
            "8291379"
          ]
        }
      ]
    }
  }
}

{

  "error-code": "invalid-request",

  "message": "items size 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 API based 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

arrow_drop_down How long does it take to reflect the newly added items in MoEngage

All MoEngage catalog APIs operate synchronously. This means that every catalog API request is processed in real time, and you can see the changes instantly.

arrow_drop_down What are the error codes?

Each error codes are 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.

arrow_drop_down Is it possible to change the data type of an attribute once an API catalog is created?

No, the datatype can not be changed once an attribute has be defined in the catalog. You can add a new attribute to the catalog with a different datatype as needed.