> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Update Subscription Preferences

> This API updates subscription category preferences in bulk. You can use this API to update the user preferences to MoEngage in large volumes.


#### Rate Limit

The rate limit is 100 RPM and 360k per day.


## OpenAPI

````yaml /api/subscription-categories/subscription-categories.yaml post /category-subscription/user-preferences
openapi: 3.0.3
info:
  title: MoEngage Subscription Categories API
  description: >
    Enables you to fetch and update email subscription preferences on your
    MoEngage dashboard.


    This API provides endpoints for:

    * **Get Preferences**: Fetches subscription preferences for a specific user.

    * **Update Preferences**: Updates preferences for a specific user (e.g.,
    from a landing page).

    * **Bulk Update Preferences**: Updates preferences for a batch of users.


    Authentication is handled via Basic Auth (Workspace ID as username, Data API
    Key as password) and the `MOE-APPKEY` header.
  version: '1.0'
servers:
  - url: https://api-{dc}.moengage.com/v1
    description: MoEngage API Server
    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: Subscription Preferences
    description: Manage user email subscription preferences.
paths:
  /category-subscription/user-preferences:
    post:
      tags:
        - Subscription Preferences
      summary: Bulk Update Subscription Preferences
      description: >
        This API updates subscription category preferences in bulk. You can use
        this API to update the user preferences to MoEngage in large volumes.
      operationId: bulkUpdateSubscriptionPreferences
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
      requestBody:
        required: true
        description: A list of preference updates for multiple users.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdatePreferencesRequest'
      responses:
        '200':
          description: Your request has been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                message: Your request has been processed
        '400':
          description: >-
            Bad Request. Returned when payload limit exceeded or categories
            missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                categories_required:
                  summary: Categories Required
                  value:
                    title: Categories Required
                    description: Categories Preferences Required
                payload_limit:
                  summary: Payload Limit Exceeded
                  value:
                    title: Payload Limit Exceeded
                    description: Payload limit is set to 50
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    AppKeyHeader:
      name: MOE-APPKEY
      in: header
      required: true
      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)**.
      schema:
        type: string
  schemas:
    BulkUpdatePreferencesRequest:
      type: object
      required:
        - channel
        - user_preferences
      properties:
        channel:
          type: string
          enum:
            - email
          description: >-
            This field contains the name of the channel. Allowed values -
            "channel": "email"
          example: email
        user_preferences:
          type: array
          description: A list of user preference objects to update. Maximum 50 per request.
          maxItems: 50
          items:
            $ref: '#/components/schemas/UserPreferenceEntry'
      example:
        channel: email
        user_preferences:
          - customer_id: john@example.com
            categories:
              Promotional: false
              Transactional: false
              Special Offers: true
            unsubscribe_all: false
          - customer_id: mike@example.com
            categories:
              Transactional: true
              Promotional: false
              Special Offers: true
            unsubscribe_all: false
          - customer_id: doe@example.com
            categories:
              Product Updates: true
              New arrivals: false
              Recommendations: true
            unsubscribe_all: false
    SuccessResponse:
      type: object
      properties:
        message:
          type: string
          description: A brief description of the request status in the case of success.
    ErrorResponse:
      type: object
      properties:
        title:
          type: string
          description: The error type.
        description:
          type: string
          description: The error description.
    UserPreferenceEntry:
      type: object
      required:
        - customer_id
        - categories
        - unsubscribe_all
      properties:
        customer_id:
          type: string
          description: >-
            The unique identifier denoting the customer (ID on the user profile
            page) for whom you are updating the subscription preferences.
          example: john@example.com
        categories:
          $ref: '#/components/schemas/SubscriptionCategories'
        unsubscribe_all:
          type: boolean
          description: Set to **true** to unsubscribe the user from all categories.
    SubscriptionCategories:
      type: object
      description: >
        A JSON Object that contains the subscription preferences of the
        customer.

        `category_name` is the unique category name in MoEngage.
      additionalProperties:
        type: boolean
      example:
        Promotions: true
        Updates: false
        Recommendations: true
        Newsletter: false
  responses:
    Unauthorized:
      description: >-
        Authorization Failure. Returned when authorization fails due to
        incorrect APP KEY/HTTP Auth Header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            auth_required:
              summary: Auth Failure
              value:
                title: Authentication required
                description: No identity information found.
            missing_header:
              summary: Missing Header
              value:
                title: Header required
                description: MOE-APPKEY missing in Header
    Conflict:
      description: >-
        API SECRET not configured. Returned when the authorization fails due to
        the APP SECRET key not being set on the Dashboard.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            title: API SECRET not configured
            description: >-
              This response is returned when the authorization fails due to the
              APP SECRET key not being set on the Dashboard.
    TooManyRequests:
      description: >-
        Rate Limit Breach. The number of requests per minute has exceeded the
        limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            title: Rate-Limit Reached
            description: Exceeded rate limit for this url
    InternalServerError:
      description: >-
        Internal Server Error. Returned when the system runs into an unexpected
        error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            title: Internal Error
            description: Please Contact Moengage Team
  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 **Data**
        tile.


        For more information on authentication and getting your credentials,
        refer
        [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

````