Add Items

This API ingests items into an existing catalog as long as the attributes provided during ingestion match the attributes provided during catalog creation.

POST /catalog/{catalog_id}/items

Add Items

cURL

curl --request POST \
  --url https://api-{dc}.moengage.com/v1/catalog/{catalog_id}/items \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'MOE-APPKEY: <moe-appkey>' \
  --data '
{
  "items": [
    {
      "id": "item-sku-123",
      "title": "Classic T-Shirt",
      "link": "https://example.com/products/item-123",
      "image_link": "https://example.com/images/item-123.jpg",
      "brand_attribute": "Super Tech",
      "in_stock": true,
      "price": 19.99,
      "sale_start_date": "2025-08-27T19:26:38.00Z",
      "store_location": "12.9716,77.5946"
    }
  ]
}
'

200

Example

{
  "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": "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"
          ]
        }
      ]
    }
  }
}

Rate Limit

• Request limit: You can ingest 100 items per minute OR 1000 items per hour. You can ingest up to 50 items per request.

• Payload size limit: 5 MB only when Content-Length header is provided.

Authorizations

Authorization · string · header · required

Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.

• Username: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
• Password: Use your API Key, which you can find within the Campaign report/Business events/Custom templates/Catalog API/Inform Report tile.

For more information on authentication and getting your credentials, refer here.

Headers

MOE-APPKEY · string · required

This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).

Path Parameters

catalog_id · string · required

The unique identifier for the catalog, obtained during catalog creation.

Body

application/json

items · object[] · required

An array of item objects to add to the catalog. Each item must contain the mandatory attributes (id, title, link, image_link), and may include any custom attributes you have defined on the catalog. Custom attributes must already exist on the catalog (added at creation or via Add Catalog Attributes).

Maximum array length: 50

Show child attributes

Response

200

application/json

OK. The ingestion request was processed. The response body contains details on valid and invalid item counts.

message · object

Show child attributes