Update Existing Items in a Catalog

You can use this API to update items with new attribute values. Attributes must adhere to the data type defined and only 50 items are allowed to be updated in a single request.

API Endpoint

PATCH 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 encapsulates a list of items with new attribute values to be updated.

Key	Required	Values	Description
id	Required	String	For certain updates to occur, the unique item ids of those items must be provided.
attributes	Required	JSON Object	Each item in the catalog will have various attributes. This field indicates the attributes per item to be updated in a catalog.

Response

Key

Data Type

Description

message

JSON Object

message provides the details of request processing.

If the request is unsuccessful, this field will explain the reason for the failure.

If the request is successful, message will have details of valid and invalid tagged items in the request and respective further details.

valid: If the item is considered valid, the API will return a valid count and ingest 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 failed to add items will be shown under this key.
details - the details JSON object shows deeper details on type of errors occurred during while adding these items in the catalog. details key consists of an errorId, error message, count of failed items and list of failed item ids per error type.

An errorId is a shorthand unique representation for the type of error. The errorId helps providing a quick reference that can be used to diagnose, troubleshoot, and address the problem based on a predefined set of error conditions. An error message describes why the processing failure reason.

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.

Response Codes

Status Code	Request State	Description
200	Success	Items updated successfully.
400	Bad Request	Bad request, update failed, won't occur generally, as the request is validated before processing.
401	Unauthenticated	The request does not have valid authentication credentials.
403	Forbidden	The request is not authorized.
404	Page not found	Catalog not found.
413	Content Too Large	Request entity too large.
429	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.
invalid-item-attribute	The provided item attribute is not part of the defined catalog schema. Please check your catalog schema and try again. Undefined attributes: [<list of attribute_names>]
invalid-datatype-attribute	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
item-not-found	The item id does not exist in the catalog. You need to provide a valid item id.

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

Add sample cURL requests here (payload).

Example:

curl --location --globoff --request PATCH '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": "{{Existing_item_ID}}",
      "attributes": {
        "{{attribute_name}}": "{{updated_value}}"
      }
    },
    
    {
      "id": "test2",
      "attributes": {
        "price": 98
      }
    }
  ]
}'

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": "item-not-found",
          "message": "Item with id %s not found in the catalog. Please check the item id and try again.",
          "count": 1,
          "document_ids": [
            "567890"
          ]
        },
        {
          "error-id": "missing-mandatory-attrs",
          "message": "items does not have all mandatory attributes present. Mandatory attributes: id, link, image_link, title",
          "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": "attribute-casting-failure",
          "message": "Error while casting attribute %s with value BLR to data type geopoint",
          "count": 1,
          "document_ids": [
            "7523675"
          ]
        },
        {
          "error-id": "invalid-attributes",
          "message": "Some of the attributes are not defined in the catalog schema: (shipping_city)",
          "count": 2,
          "document_ids": [
            "312",
            "8291379"
          ]
        },
        {
          "error-id": "invalid-attributes",
          "message": "Some of the attributes are not defined in the catalog schema: (recommended_price)",
          "count": 1,
          "document_ids": [
            "78361487"
          ]
        }
      ]
    }
  }
}

{
  "error-code": "invalid-request",
  "message": "Bad request, update failed"
}

{
  "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": "Catalog not found for the given id"
}

{
    "error-code": "payload-size-too-large",
    "message": "The payload size is too large. Maximum allowed size is 5MB."
}


    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 updates for the 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 Can I add a new attribute in payload while sending updates for existing items?

Before updating existing items with new attributes, you must first add the new attribute to the catalog schema using the 'Add catalog attribute' API. Only then will your update requests for including new attributes be successful.

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.