Create a Catalog

This API allows you to create a new catalog with a unique name and specify the necessary attributes along with their respective data types.

API Endpoint

POST https://api-0X.moengage.com/v1/catalog

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

Key

Required

Values

Description

name

Required

String

This field indicates the name of the Catalog. The name must be unique.

"name": "exampleCatalog"

attributes

Required

Array

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 maximum of 50 attributes including the 4 mandatory attributes.

Note: Your request could fail if the mandatory attributes are absent from your payload.

price_currency

Required

String

This represents the currency in which the prices of the items in the catalog are denominated. The value must be one of the following:

USD, CAD, EUR, AED, AFN, ALL, AMD, AOA, ARS, AUD, AZN, BAM, BDT, BGN, BHD, BIF, BND, BOB, BRL, BWP, BYR, BZD, CDF, CHF, CLP, CNY, COP, CRC, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, GBP, GEL, GHS, GNF, GTQ, HKD, HNL, HRK, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KHR, KMF, KRW, KWD, KZT, LBP, LKR, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MOP, MUR, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SDG, SEK, SGD, SOS, SYP, THB, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VND, XAF, XOF, YER, ZAR, ZMK.

Response

Key	Data Type	Description
catalog_id	String	This field contains the unique ID corresponding to a successful catalog creation request and needs to be stored by you. This catalog ID is used as header input for item ingestion, updates, or any kind of catalog modifications in later stage.
error-code	String	Each error codes are unique and serve as a 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.
message	String	Along 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.

Response Codes

Status Code	Request State	Description
201	Success	Catalog created successfully.
400	Bad Request	This response is returned when the required parameters are missing from the request, when the provided parameters are invalid, or when a template already exists with the same version, name, or ID.
401	Unauthenticated	The request does not have valid authentication credentials.
403	Forbidden	The request is not authorized.
413	Content Too Large	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	The data type provided for some of the attributes is invalid. Provided value: <provided datatype> You can add attributes with valid data types(bool, double, string, datetime, geopoint) only.
400	invalid-request	Something went wrong with your request. Please contact the MoEngage team for further assistance.
400	missing-mandatory-attributes	You must include mandatory attributes: id, title, link, and image_link with string data type and try again. Invalid or absent attributes: <missing attributes>
400	catalog-limit-exceeded	You have exceeded the total limit of 35 catalogs for your account. You need to delete unused catalogs from the dashboard and try again.
400	attribute-limit-exceeded	Your catalog has exceeded the maximum limit of 50 attributes per catalog. Please reduce the number of attributes and try again.
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.
409	duplicate-catalog-name	Catalog name already exists. Please use a different name for your catalog and try again.
413	payload-size-exceeded	Your payload size exceeds the 5MB limit. Please 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.
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' \
--header 'MOE-APPKEY: {{DATA_APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic e3tEQVRBX0FQUF9JRH19Ont7REFUQV9BUElfS0VZfX0=' \
--data '{
    "name": "{{Catalog_Name}}",
    "price_currency": "INR",
    "attributes": [
        {
            "name": "title",
            "type": "string"
        },
        {
            "name": "link",
            "type": "string"
        },
        {
            "name": "id",
            "type": "string"
        },
        {
            "name": "image_link",
            "type": "string"
        },
        {
            "name": "{{attribute_name}}",
            "type": "{{attribute_data_type}}"
        }
    ]
}'

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.

{
  "catalog_id": "{{Catalog_id}}"
}

{
  "error-code": "duplicate-catalog-name",
  "message": "Catalog name already exists. Please use a different name for your catalog and try again."
}

{
  "error-code": "invalid-request",
  "message": "The data type provided for some of the attributes is invalid. Provided value: <provided datatype>  You can add attributes with valid data types - [bool, double, string, datetime, geopoint] only"
}

{
  "error-code": "missing-mandatory-attributes",
  "message": "You must include mandatory attributes: id, title, link, and image_link with string data type and try again. Invalid or absent attributes: <missing attributes>"
}

{
  "error-code": "catalog-limit-exceeded",
  "message": "You have exceeded the total limit of 35 catalogs for your account. You need to delete unused catalogs from the dashboard and try again."
}

{

  "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": "too-many-attributes",
  "message": "Maximum allowed attributes is 50"
}


    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 What are the benefits of using the API catalog over a file-based catalog?

API catalogs automate real-time updates such as price and quantity. They offer improved efficiency and scalability by updating only specific products, unlike file-based catalogs, which require the replacement of the whole file at each processing schedule. These APIs can be accessed and used to update from any location.

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.