Overview
The MoEngage Catalog API allows you to programmatically manage product and item catalogs. Use these endpoints to create new catalogs, define custom schemas, and perform bulk operations for ingesting, updating, or deleting items.Authentication Requirement: This API requires Basic Auth (Workspace ID as username and API Key as password) AND the
MOE-APPKEY header. Ensure both are provided for every request.Catalog API Endpoints
The Catalog API consists of the following operations:- Create a New Catalog
- Add Catalog Attributes
- Ingest Items into the Catalog
- Update Existing Items
- Delete Existing Items
API Constraints & Limits
| Feature | Limit |
|---|---|
| Rate Limit | 100 requests/minute OR 1000 requests/hour |
| Max Payload Size | 5MB (requires Content-Length header) |
| Batch Size | Max 50 items per Ingest/Update/Delete request |
| Max Attributes | 50 attributes per catalog |
| Max Catalogs | 35 catalogs per account |
Supported Data Types
When defining attributes or ingesting items, ensure the values match these supported types:| Type | Description |
|---|---|
string | Textual data |
bool | Boolean (true/false) |
double | Numeric/Floating point values |
datetime | Date and time format |
geopoint | Geographical coordinates |
Notes
Mandatory Attributes: Every catalog item must include the following four mandatory attributes as strings:
id: The unique identifier for the item.title: The name of the item.link: The deep link or URL to the item page.image_link: The URL of the primary product image.
catalog_id returned upon successful creation is a UUID. You must store this ID as it is required as a path parameter for all subsequent item management requests.FAQs
Catalog Management
What happens if I try to create a catalog with a name that already exists?
What happens if I try to create a catalog with a name that already exists?
The API will return a
409 Conflict error with the error code duplicate-catalog-name. Catalog names must be unique within your workspace.Can I add new attributes to a catalog after it has been created?
Can I add new attributes to a catalog after it has been created?
Yes, you can use the Add Catalog Attributes (PATCH) endpoint. Note that if you send attributes that already exist in the schema, they will be ignored and listed in the
duplicate-item-attributes array in the response.What is the maximum number of custom attributes I can define?
What is the maximum number of custom attributes I can define?
You can define up to 50 attributes per catalog, including the 4 mandatory attributes.
What are the benefits of using the API catalog over a file-based catalog?
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.
What are the error codes?
What are the error codes?
Each error code is a 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.
Is it possible to change the data type of an attribute once an API catalog is created?
Is it possible to change the data type of an attribute once an API catalog is created?
No, the datatype cannot be changed once an attribute has been defined in the catalog. You can add a new attribute to the catalog with a different datatype as needed.
How many attributes can I add to a catalog?
How many attributes can I add to a catalog?
A maximum of 50 attributes can be added to the catalog.
Can I add a new attribute in payload while sending updates for existing items?
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.
What happens if my payload consist of items which are not in catalog?
What happens if my payload consist of items which are not in catalog?
The request will be processed successfully marking such items as invalid. The response will include the count of these invalid item IDs.
Item Ingestion & Updates
How does the API handle partial failures during bulk ingestion?
How does the API handle partial failures during bulk ingestion?
The API returns a
200 OK with a detailed breakdown. The response body will include a valid count and an invalid count with a details array specifying which document_ids failed and why (e.g., data type mismatch or missing attributes).Can I update an item ID?
Can I update an item ID?
No. The
id is the primary key. To change an ID, you must delete the existing item and ingest it as a new item.Is there a limit to how many items I can delete at once?
Is there a limit to how many items I can delete at once?
Yes, the bulk-delete endpoint supports a maximum of 50 item IDs per request.
How long does it take to reflect the newly added items or updates in MoEngage
How long does it take to reflect the newly added items or updates 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.