Add New Catalog Attributes

You can use this API to add new attributes to the catalog. If the API request contains attributes that already exist, they will not be added again.

API Endpoint

PATCH https://api-0X.moengage.com/v1/catalog/{{Catalog_id}}/attributes

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

attributes

Required

Array

This field indicates a list of attributes that you want to add in your existing catalog schema. These attributes can be information related to your catalog items for example - color, weight, quantity etc.

We support the following data types:

boolean
date
string
float
geopoint

Response

Key	Data Type	Description
success	Boolean	This field contains a brief description of the request status in the case of success.
duplicate-item-attributes	Array	If some of your payload attributes are already present in the catalog, they will be returned as a list under this key.
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
202	Success	Response contains the list of attributes that were already present in the catalog. Rest all were successfully added.
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	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.
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.

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 --request PATCH 'https://api-{{0X}}.moengage.com/v1/catalog/{{catalog_ID}}/attributes' \
--header 'MOE-APPKEY: {{DATA_APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic e3tEQVRBX0FQUF9JRH19Ont7REFUQV9BUElfS0VZfX0=' \
--data '{
    "attributes": [
        {
            "name": "{{new_attribute_name}}",
            "type": "{{attribute_data_type}}"
        },
        
        {
            "name": "description",
            "type": "string"
        }
    ]
}'

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.

{
  "success": true,
  "duplicate-item-attributes": [
    "colour",
    "weight"
  ]
}

{
  "error-code": "attribute-exists",
  "message": "Attribute already exists in the catalog"
}

{

  "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 How many attributes can I add to a catalog?

A maximum of 50 attributes can be added to the catalog.

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.