MoEngage Items API

openapi: 3.2.0
info:
  title: MoEngage Catalog Items API
  description: 'This API allows for the management of product and item catalogs, including **creation**, **attribute definition**, **item ingestion, updates, deletion**, and **retrieval**.


    Authentication is handled via **Basic Auth** (using your Workspace ID as username and API Key as password), and all requests additionally require the `MOE-APPKEY` header (Workspace ID).


    The API has a platform-wide rate limit of **100 requests/minute OR 1000 requests/hour**, with a maximum payload size of **5MB**.'
  x-mint:
    content: '#example 500 max #

      '
  version: '1.0'
servers:
- url: https://api-{dc}.moengage.com/v1
  variables:
    dc:
      default: '01'
      description: The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
tags:
- name: Items
  description: Operations related to ingesting, updating, and deleting items within a catalog.
paths:
  /catalog/{catalog_id}/items:
    post:
      tags:
      - Items
      summary: Add Items
      operationId: ingestCatalogItems
      description: This API ingests items into an existing catalog as long as the attributes provided during ingestion match the attributes provided during catalog creation.
      x-mint:
        content: '#### 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.

          '
      parameters:
      - name: MOE-APPKEY
        in: header
        description: 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)**.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/CatalogIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  maxItems: 50
                  description: 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).
                  items:
                    $ref: '#/components/schemas/CatalogItem'
      responses:
        '200':
          description: OK. The ingestion request was processed. The response body contains details on valid and invalid item counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestUpdateResponse'
              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'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      tags:
      - Items
      summary: Update Items
      operationId: updateCatalogItems
      description: This API updates items with new attribute values. Attributes must adhere to the data type defined.
      x-mint:
        content: '#### Rate Limit


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


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

          '
      parameters:
      - name: MOE-APPKEY
        in: header
        description: 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)**.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/CatalogIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  maxItems: 50
                  description: An array of item updates. Each object must contain the item `id` and the `attributes` to update.
                  items:
                    $ref: '#/components/schemas/ItemUpdate'
            example:
              items:
              - id: Existing_item_ID
                attributes:
                  attribute_name: updated_value
              - id: test2
                attributes:
                  price: 98
                  sale_start_date: '2025-08-27T19:26:38.00Z'
                  store_location: 12.9716,77.5946
      responses:
        '200':
          description: OK. The update request was processed. The response body contains details on valid and invalid item counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestUpdateResponse'
              example:
                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: invalid-attributes
                      message: 'Some of the attributes are not defined in the catalog schema: (shipping_city)'
                      count: 2
                      document_ids:
                      - '312'
                      - '8291379'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /catalog/{catalog_id}/items/bulk-delete:
    post:
      tags:
      - Items
      summary: Delete Items
      operationId: deleteCatalogItems
      description: This API deletes existing items in a given catalog.
      x-mint:
        content: '#### Rate Limit


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


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

          '
      parameters:
      - name: MOE-APPKEY
        in: header
        description: 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)**.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/CatalogIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  maxItems: 50
                  description: An array of item IDs to delete from the catalog.
                  items:
                    type: string
                    example: item_id_123
            example:
              items:
              - '{{item_ID}}'
      responses:
        '202':
          description: Accepted. The bulk delete request was processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: object
                    properties:
                      valid:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: The number of items successfully deleted.
                      invalid:
                        type: object
                        properties:
                          count:
                            type: integer
                            description: The number of items that were not found and could not be deleted.
              example:
                message:
                  valid:
                    count: 0
                  invalid:
                    count: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /catalog/{catalog_id}/items/search:
    post:
      tags:
      - Items
      summary: Get Items
      operationId: getItemDetails
      description: This API retrieves item attribute details for catalog items using their unique item IDs. The attributes can include the title, price, category, link, image_link, and the respective creation date.
      x-mint:
        content: '#### Rate Limit


          - Request limit: You can get 100 item attribute details per minute OR 1000 item attribute details per hour. You can request up to 50 items per request.


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


          <Note>

          The limit is a COMBINED limit across all Catalog APIs for a specific user.

          </Note>

          '
      parameters:
      - name: MOE-APPKEY
        in: header
        description: 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)**.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/CatalogIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  maxItems: 50
                  description: 'A list of unique IDs (strings) that represent the items you want to fetch. This field accepts a maximum of **50 item IDs** per request. If the count exceeds this limit, the request results in an error.


                    **Note**: The request may fail if mandatory attributes are missing from the item configuration.

                    '
                  items:
                    type: string
                  example:
                  - P001
                  - P002
                  - P003
                  - P004
            example:
              items:
              - P001
              - P002
              - P003
              - P004
      responses:
        '200':
          description: Items retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetItemDetailsResponse'
              example:
                items:
                - catalog_id: '{{catalog_id}}'
                  feed_id: '{{feed_id}}'
                  title: string
                  description: string
                  link: https://link.in/
                  image_link: https://link.in/
                  price_currency: USD
                  creation_date: '2024-05-10T07:03:00.18Z'
                  last_updated: '2024-05-10T07:03:00.18Z'
                  product_id: string
                  price: 29.99
                  date: '2022-04-05T00:00:00.00Z'
                  sale_start_date: '2025-08-27T19:26:38.00Z'
                  store_location: 12.9716,77.5946
        '400':
          description: Bad Request - Invalid request format or item count validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error-code: invalid-request
                message: Item count should be greater than 0 and less than or equal to 50
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    CatalogIdPath:
      name: catalog_id
      in: path
      required: true
      description: The unique identifier for the catalog, obtained during catalog creation.
      schema:
        type: string
  responses:
    NotFound:
      description: Not Found - The specified resource (catalog) could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error-code: catalog-not-found
            message: We could not find any API based catalog for the provided catalog id.
    Unauthorized:
      description: Unauthorized - The request does not have valid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error-code: request-unauthenticated
            message: Your request is unauthorized. Please verify your credentials and try again.
    BadRequest:
      description: Bad Request - The request is improperly formatted, or contains missing/invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid-datatype:
              value:
                error-code: invalid-request
                message: The data type provided for some of the attributes is invalid.
            invalid-json:
              value:
                error-code: invalid-request
                message: The request body is not a valid JSON. Please provide a valid JSON request body.
            limit-exceeded:
              value:
                error-code: invalid-request
                message: items size should be greater than 0 and less than or equal to 50
    Forbidden:
      description: Forbidden - The client does not have access rights to the Catalog APIs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error-code: request-denied
            message: Your account does not have access to the Catalog APIs.
    PayloadTooLarge:
      description: Payload Too Large - The request payload exceeds the 5MB limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error-code: payload-size-exceeded
            message: Your payload size exceeds the 5MB limit. Please reduce the payload size and try again.
    TooManyRequests:
      description: 'Too Many Requests - The rate limit for the API has been exceeded.


        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.'
  schemas:
    CatalogItem:
      type: object
      required:
      - id
      - title
      - link
      - image_link
      properties:
        id:
          type: string
          description: The unique identifier for the catalog item.
        title:
          type: string
          description: The title or name of the catalog item.
        link:
          type: string
          format: uri
          description: The deep link or URL to the item's page.
        image_link:
          type: string
          format: uri
          description: The URL of the primary image for the item.
      additionalProperties: true
      example:
        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
    IngestUpdateResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            valid:
              type: object
              properties:
                count:
                  type: integer
                  description: The number of items successfully processed.
            invalid:
              type: object
              properties:
                count:
                  type: integer
                  description: The number of items that failed processing.
                details:
                  type: array
                  items:
                    type: object
                    properties:
                      error-id:
                        type: string
                        description: A unique ID indicating the type of ingestion/update failure.
                        example: duplicate-item-ids
                      message:
                        type: string
                        description: The reason for the failure.
                        example: Item ids within a catalog must be unique.
                      count:
                        type: integer
                        description: The number of items that failed due to this specific error.
                        example: 1
                      document_ids:
                        type: array
                        items:
                          type: string
                        description: The IDs of the items that failed.
                        example:
                        - item_id_xyz
    Error:
      type: object
      properties:
        error-code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable description of the error.
    GetItemDetailsResponse:
      type: object
      properties:
        items:
          type: array
          description: A list of catalog item objects matching the requested item IDs.
          items:
            type: object
            properties:
              catalog_id:
                type: string
                description: The unique identifier for the catalog.
              feed_id:
                type: string
                description: The feed ID associated with the item.
              title:
                type: string
                description: The title or name of the catalog item.
              description:
                type: string
                description: The description of the catalog item.
              link:
                type: string
                format: uri
                description: The deep link or URL to the item's page.
              image_link:
                type: string
                format: uri
                description: The URL of the primary image for the item.
              price_currency:
                type: string
                description: The ISO 4217 currency code for the item price.
              creation_date:
                type: string
                format: date-time
                description: The date and time when the item was created.
              last_updated:
                type: string
                format: date-time
                description: The date and time when the item was last updated.
              product_id:
                type: string
                description: The product ID of the item.
              price:
                type: number
                format: double
                description: The price of the item.
              date:
                type: string
                format: date-time
                description: A date attribute associated with the item.
            additionalProperties: true
    ItemUpdate:
      type: object
      required:
      - id
      - attributes
      properties:
        id:
          type: string
          description: The unique ID of the item to update.
        attributes:
          type: object
          description: 'A key-value map of attributes to update for the item. The keys

            must match existing attributes in the catalog schema, and values

            must match the defined data types.

            '
          additionalProperties: true
          example:
            price: 24.99
            in_stock: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: '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](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

        '
    AppKeyHeader:
      type: apiKey
      in: header
      name: MOE-APPKEY
      description: '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)**.

        '