openapi: 3.0.3
info:
  title: Coupon List API 🏷️
  description: |
    API for managing coupon lists within the MoEngage system. This includes creating, fetching, updating, activating, archiving lists, uploading coupon files, managing files, and generating usage reports.
    Authentication is via Basic Auth using your **Workspace ID** as username and an **API Key** as password.
  version: '1.0'
servers:
  - url: 'https://api-{dc}.moengage.com/v1'
    description: The MoEngage Coupon Management API endpoint. The **X** in the URL is replaced by the data center number (e.g., 01, 02, 03).
    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."
tags:
  - name: Coupon Lists
    description: Operations related to defining, managing status (active/archive), and modifying coupon list metadata.
  - name: Coupon Files
    description: Operations related to uploading coupon codes via files and checking/managing file processing status.
  - name: Reports
    description: Operations related to generating usage reports for coupon lists.
paths:
  /coupon-list:
    post:
      tags:
        - Coupon Lists
      summary: Create a Coupon List
      operationId: createCouponList
      description: |
        This API creates single-use coupon codes. You can use this API to create and organize distinct lists for different coupon code categories.
      x-mint:
        content: |
          <Note>
            **Information**
            
            This API creates the coupon list with basic specifications only. The coupons should be added using [Upload the Coupons](https://www.moengage.com/docs/api/coupon-files/upload-a-coupon-file-to-the-coupon-list) API to this coupon list before utilizing it in campaigns.
          </Note>

          #### Rate Limit
          You can create 100 coupon lists per day.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCouponListRequest'
      responses:
        '201':
          description: |
            Success
            Indicates that the request is successful and the coupon list creation request is accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: This field consists of the unique name of the coupon list corresponding to a successful coupon list creation request.
                  label:
                    type: string
                    description: This field consists of the label name for the coupon list corresponding to a successful coupon list creation request.
                  expires_at:
                    type: string
                    description: This field consists of the expiry date of the coupon list in yyyy-mm-dd format corresponding to a successful coupon list creation request.
                  created_by:
                    type: string
                    description: This field consists of the user name who created the coupon list corresponding to a successful coupon list creation request.
                  email_alert_subscribers:
                    type: array
                    items:
                      type: string
                    description: This field consists of the email address of the coupon list subscriber corresponding to a successful coupon list creation request.
                  alert_conditions:
                    type: object
                    description: This field consists of the alert conditions and the statuses specified while creating the coupon list.
                  status:
                    type: string
                    description: Once the coupon list creation request is accepted, the list status will show ACTIVE.
                  _id:
                    type: string
                    description: This field contains the unique ID corresponding to a successful coupon list creation request. This ID is used as a parameter for fetching, updating, or archiving coupon lists.
              example:
                name: "Example Name"
                label: "Sample Label"
                expires_at: "2024-10-31T18:29:00"
                created_by: "John"
                email_alert_subscribers:
                  - "john.doe@example.com"
                alert_conditions:
                  success_alert: true
                  failure_alert: true
                  expiry_alert:
                    alert: true
                    days_before: 1
                  coupon_shortage_alert:
                    alert: true
                    threshold_count: 10
                status: "ACTIVE"
                _id: "6721d00eefc476c0f67e0d05"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                duplicate_name:
                  summary: Duplicate Name
                  value:
                    error:
                      code: "duplicate-coupon-list-name"
                      message: "The coupon list name already exists. Please enter a unique name and try again."
                duplicate_label:
                  summary: Duplicate Label
                  value:
                    error:
                      code: "duplicate-coupon-list-label"
                      message: "The coupon list label already exists. Please enter a unique label and try again."
                missing_attributes:
                  summary: Missing Attributes
                  value:
                    error:
                      code: "missing-mandatory-attributes"
                      message: "Missing mandatory key. Please verify and try again."
                invalid_request:
                  summary: Invalid Request
                  value:
                    error:
                      code: "invalid-request"
                      message: "The requested JSON is incorrect. Please verify and try again."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Please verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Please contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."
    get:
      tags:
        - Coupon Lists
      summary: Fetch All Coupon Lists
      operationId: fetchAllCouponLists
      description: |
        This API fetches all created coupon lists in a specific workspace. By default, this API returns the coupon lists marked with an *ACTIVE* status. In return, it offers detailed specifications of the active coupon lists, respective configurations, statuses, expiry dates, and alert conditions, including on-time data on the total coupons added and those that are currently available.
      x-mint:
        content: |
          <Note>
            **Information**
            
            There is no request body or content to send for this request except for the headers and parameters.
          </Note>

          #### Rate Limit
          You can fetch 10,000 coupon lists per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - name: status
          in: query
          required: false
          description: |
            This field contains an array of all the coupons with their respective attributes based on the following statuses you provide in the request parameter:
            
            * ACTIVE - to view only active coupon lists
            * ARCHIVED - to view only archived coupon lists
            * EXPIRED - to view only expired coupon lists
            
            **Note**: Not specifying any status will display all the existing coupon lists together.
          schema:
            type: string
            enum: [ACTIVE, ARCHIVED, EXPIRED]
      responses:
        '200':
          description: |
            Success
            Indicates that the request is successful and all the active and/or archived coupon lists are fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: This field consists of the unique name of the coupon list.
                        label:
                          type: string
                          description: This field consists of the label name for the fetched coupon list.
                        expires_at:
                          type: string
                          description: This field consists of the expiry date of the coupon list in yyyy-mm-dd format.
                        status:
                          type: string
                          description: |
                            This field shows one of the following statuses of the fetched coupon list:
                            * ACTIVE
                            * EXPIRED
                            * ARCHIVED
                        total_coupons:
                          type: integer
                          description: This field consists of the total number of coupons in the coupon list.
                        created_at:
                          type: string
                          description: This field consists of the date and time the coupon list was created.
                        updated_at:
                          type: string
                          description: This field consists of the date and time of the most recent update to the coupon list.
                        email_alert_subscribers:
                          type: string
                          description: This field consists of the email address of the coupon list subscriber.
                        alert_conditions:
                          type: object
                          description: This field consists of the alert conditions and their statuses specified while creating the coupon list.
                        available_coupons:
                          type: integer
                          description: This field consists of the available number of coupons in coupon list.
                        personalization_snippet:
                          type: string
                          description: This field consists of the personalization snippet of the coupon list.
                        created_by:
                          type: string
                          description: This field consists of the user name who created the fetched coupon list.
                        _id:
                          type: string
                          description: This field contains the unique ID corresponding to a successful coupon list fetch request. This ID is also used to update and archive coupon lists.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "bad-request"
                  message: "Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."

  /coupon-list/{coupon_list_id}:
    get:
      tags:
        - Coupon Lists
      summary: Fetch Coupon List Details
      operationId: fetchCouponList
      description: |
        This API retrieves the specifications of a particular coupon list. It includes information such as configurations, statuses, expiry dates, and alert conditions with real-time counts of added and currently available coupons. Using this API, you can easily access and manage critical data about individual coupon lists.
      x-mint:
        content: |
          <Note>
            **Information**
            
            There is no request body or content to send for this request except for headers and parameters.
          </Note>

          #### Rate Limit
          You can fetch 10000 coupon lists per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
      responses:
        '200':
          description: |
            Success
            Indicates that the request is successful and the coupon list is fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: This field consists of the unique name of the coupon list.
                  label:
                    type: string
                    description: This field consists of the label name for the fetched coupon list.
                  expires_at:
                    type: string
                    description: This field consists of the expiry date of the coupon list in yyyy-mm-dd format.
                  status:
                    type: string
                    description: |
                      This field shows one of the following statuses of the fetched coupon list:
                      * ACTIVE
                      * EXPIRED
                      * ARCHIVED
                  total_coupons:
                    type: integer
                    description: This field consists of the total number of coupons in the coupon list.
                  created_at:
                    type: string
                    description: This field consists of the date and time the coupon list was created.
                  updated_at:
                    type: string
                    description: This field consists of the date and time of the most recent update to the coupon list.
                  email_alert_subscribers:
                    type: array
                    items:
                      type: string
                    description: This field consists of the email address of the coupon list subscriber.
                  alert_conditions:
                    type: object
                    description: This field consists of the alert conditions and their statuses specified while creating the coupon list.
                  available_coupons:
                    type: integer
                    description: This field consists of the available number of coupons in coupon list.
                  personalization_snippet:
                    type: string
                    description: This field consists of the personalization snippet of the coupon list.
                  created_by:
                    type: string
                    description: This field consists of the user name who created the fetched coupon list.
                  _id:
                    type: string
                    description: This field contains the unique ID corresponding to a successful coupon list fetch request. This ID is also used to update and archive coupon lists.
              example:
                name: "signup coupons"
                label: "signup_coupons"
                expires_at: "2024-10-26T18:29:00.000Z"
                status: "ACTIVE"
                total_coupons: 0
                created_at: "2024-10-01T11:29:00.000Z"
                updated_at: "2024-10-01T11:39:00.000Z"
                email_alert_subscribers:
                  - "john.doe@example.com"
                alert_conditions:
                  success_alert: true
                  failure_alert: true
                  expiry_alert:
                    alert: true
                    days_before: 100
                  coupon_shortage_alert:
                    alert: true
                    threshold_count: 100
                available_coupons: 0
                personalization_snippet: "{{Coupons.CouponListName[signup_coupons]}}"
                created_by: "test_user"
                _id: "{{coupon_list_id}}"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "bad-request"
                  message: "Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."
    patch:
      tags:
        - Coupon Lists
      summary: Update a Coupon List
      operationId: updateCouponList
      description: |
        This API modifies existing coupon lists within a defined workspace. It facilitates changes to specifications like list name, expiry date, and alert settings, thereby promoting efficient coupon operations management.
      x-mint:
        content: |
          <Note>
            **Information**
            
            This API reactivates the *ARCHIVED* or *EXPIRED* coupon list upon modification, provided the list has a future expiration date.
          </Note>

          #### Rate Limit
          You can update 100 coupon lists per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: This field contains the new name of the coupon list.
                expires_at:
                  type: string
                  format: date
                  description: This field contains the new date of the coupon list in yyyy-mm-dd format.
                email_alert_subscribers:
                  type: array
                  items:
                    type: string
                    format: email
                  description: This field consists of the new email address of the coupon list subscriber. The subscriber will receive all the alerts on the coupon list in the email provided in this field.
                alert_conditions:
                  $ref: '#/components/schemas/AlertConditions'
                  description: This object contains the updated details for the alert conditions.
      responses:
        '200':
          description: |
            Success
            Indicates that the request is successful and the coupon list update request is accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: This field consists of the updated name of the coupon list.
                  label:
                    type: string
                    description: This field consists of the label name for the coupon list.
                  expires_at:
                    type: string
                    description: This field contains the updated expiration date of the coupon list in yyyy-mm-dd format.
                  status:
                    type: string
                    description: |
                      This field consists of the status of the coupon list.
                      
                      **Note:** You can only update active coupon lists.
                  total_coupons:
                    type: integer
                    description: This field consists of the total number of coupons in the coupon list.
                  created_at:
                    type: string
                    description: This field consists of the date and time the coupon list was created.
                  updated_at:
                    type: string
                    description: This field consists of the date and time of the most recent update to the coupon list.
                  email_alert_subscribers:
                    type: string
                    description: This field contains the subscriber's updated email address on the coupon list.
                  alert_conditions:
                    type: object
                    description: This field consists of the updated alert conditions and the statuses specified for the coupon list.
                  available_coupons:
                    type: integer
                    description: This field consists of the available number of coupons in coupon list.
                  created_by:
                    type: string
                    description: This field consists of the user name who created the coupon list.
                  _id:
                    type: string
                    description: This field contains the unique ID of the coupon list requested for update. This ID is used in the params to fetch and archive coupon lists.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                duplicate_name:
                  summary: Duplicate Name
                  value:
                    error:
                      code: "duplicate-coupon-list-name"
                      message: "The coupon list name already exists. Please enter a unique name and try again."
                duplicate_label:
                  summary: Duplicate Label
                  value:
                    error:
                      code: "duplicate-coupon-list-label"
                      message: "The coupon list label already exists. Please enter a unique label and try again."
                missing_attributes:
                  summary: Missing Attributes
                  value:
                    error:
                      code: "missing-mandatory-attributes"
                      message: "Missing mandatory key ''. Please verify and try again."
                invalid_request:
                  summary: Invalid Request
                  value:
                    error:
                      code: "invalid-request"
                      message: "The requested JSON is incorrect. Please verify and try again."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."

  /coupon-list/{coupon_list_id}/activate:
    put:
      tags:
        - Coupon Lists
      summary: Activate Coupon List
      operationId: activateCouponList
      description: |
        This API reactivates archived coupon lists, provided the expiry date is in the future.
      x-mint:
        content: |
          <Note>
            **Information**
            
            * Only active coupon lists can be utilized in campaigns.
            * If you need to modify the expiry date and activate a coupon list, you must use the [Update a Coupon List API](#operation/updateCouponList).
          </Note>

          #### Rate Limit
          You can activate 100 coupon lists per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - expires_at
              properties:
                expires_at:
                  type: string
                  format: date
                  description: |
                    Add a new expiry date for the coupon list in yyyy-mm-dd format.
                    
                    **Note:** Your request could fail if the mandatory attributes are absent from your payload.
      responses:
        '204':
          description: |
            Success (No content)
            Coupon list activation is successful.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "bad-request"
                  message: "Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."

  /coupon-list/{coupon_list_id}/archive:
    put:
      tags:
        - Coupon Lists
      summary: Archive a Coupon List
      operationId: archiveCouponList
      description: |
        This API transitions an active coupon list to an archived status. Upon archival, the coupon codes within the list are deleted. Consequently, any campaigns that were previously dependent on this list will no longer be able to utilize the dynamic coupon allocation.
      x-mint:
        content: |
          <Note>
            **Information**
            
            Verify the usage of a given coupon list in active or planned campaigns before archiving it.
          </Note>

          #### Rate Limit
          You can archive 100 coupon lists per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
      responses:
        '204':
          description: |
            Success (No content)
            The request is successful, and the coupon list is archived.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "bad-request"
                  message: "Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Please verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."

  /coupon-list/{coupon_list_id}/files:
    post:
      tags:
        - Coupon Files
      summary: Upload a Coupon File to the Coupon List
      operationId: uploadCouponFile
      description: |
        After you create a coupon list, you must add coupons to the list to be distributed through campaigns. If a coupon list has been running for some time, it may be running low after serving several campaigns.

        Using this API, you can replenish an older list or populate a new list by providing the URL of a file containing the coupons, thereby enabling their distribution through various campaigns. These coupons can be provided through a file, and the API requires the URL where your coupon file is hosted.
      x-mint:
        content: |
          <Note>
            **Information**
            
            Upon API request, file processing begins, and the file status will be **PENDING** by default.
            * For convenience, you can set up a callback URL to trigger when the file's processing is completed.
            * You can check the processing status using the [Fetch a Coupon File API](https://www.moengage.com/docs/api/coupon-files/fetch-a-coupon-file-from-coupon-list) to get the status separately.
          </Note>

          #### Rate Limit
          You can upload:
          * 5 coupon files to a coupon list per minute or
          * 50 coupon files to a coupon list per day

          **Note:**
          * **Payload size limit**: 64 MB for manual uploads or 100 MB for URL uploads.
          * **Additional limits**: The maximum number of coupons per coupon list is 100 million.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadCouponFileRequest'
              properties:
                name:
                  description: This field consists of the file name of the coupon list.
                file_url:
                  description: This field consists of the file path of the coupon list.
                file_url_auth_username:
                  type: string
                  description: This field consists of the coupon file username.
                file_url_auth_password:
                  type: string
                  description: This field consists of the coupon file password.
                created_by:
                  description: This field consists of the name of the subscriber who uploaded the coupon file.
                callback_url:
                  description: This field consists of the coupon file callback URL.
            examples: {}
      responses:
        '201':
          description: |
            Success
            The request was successful, and the coupon URL upload request was accepted.
            
            **Note**: The status of the URL upload is always PENDING.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: This field contains the coupon file name.
                  file_url:
                    type: string
                    description: This field consists of the file path of the coupon list.
                  created_by:
                    type: string
                    description: This field consists of the name of the subscriber who uploaded the coupon file.
                  status:
                    type: string
                    description: |
                      Once the coupon URL upload request is accepted, the response displays the following status:
                      * PENDING - The URL is waiting for approval.
                      
                      **Note:** To know the status of the coupon upload, you need to trigger the **Fetch a Coupon File API**.
                  coupons_list_id:
                    type: string
                    description: This field contains the coupon list ID that you have requested to upload the coupon file to.
                  _id:
                    type: string
                    description: This field contains the coupon file ID.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_json:
                  summary: Invalid JSON
                  value:
                    error:
                      code: "invalid-request"
                      message: "The requested JSON is incorrect. Please verify and try again."
                empty_file_url:
                  summary: Empty File URL
                  value:
                    error:
                      code: "invalid-request"
                      message: "The 'file_url' can not be empty. Please provide the coupon file url and try again."
                multiple_file_urls:
                  summary: Multiple File URLs
                  value:
                    error:
                      code: "invalid-request"
                      message: "Multiple file urls are not permitted. Please select one file url and try again."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Please verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Please contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."
    get:
      tags:
        - Coupon Files
      summary: Fetch All Coupon Files From Coupon List
      operationId: fetchAllCouponFiles
      description: |
        This API retrieves the details of each file in the given coupon list that is added and not deleted. The information retrieved will include the file's status, the number of coupons added from each file, and the respective file's addition date, thereby providing a comprehensive breakdown of each file's information for improved management and tracking.
      x-mint:
        content: |
          <Note>
            There is no request body or content to send for this request except for headers.
          </Note>

          #### Rate Limit
          You can fetch 10,000 coupon files from coupon lists per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - name: coupon_list_id
          in: path
          required: true
          description: The unique identifier for the coupon list.
          schema:
            type: string
      responses:
        '200':
          description: |
            Success
            Indicates that the request was successful and the coupon files have been fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        coupon_list_id:
                          type: string
                          description: This field contains the coupon list ID from which you fetched the coupon files.
                        name:
                          type: string
                          description: This field contains the coupon file name.
                        status:
                          type: string
                          description: |
                            This field shows one of the following statuses of the fetched coupon files:
                            * PENDING
                        file_url:
                          type: string
                          description: This field consists of the file path of the coupon list.
                        created_at:
                          type: string
                          description: This field consists of the date and time the coupon file was created.
                        updated_at:
                          type: string
                          description: This field consists of the date and time of the most recent update to the coupon file.
                        created_by:
                          type: string
                          description: This field consists of the name of the subscriber who uploaded the coupon file.
                        _id:
                          type: string
                          description: This field contains the unique ID corresponding to a successful coupon file fetch request. This ID is also used to update and archive coupon files from the coupon list.
                        added_coupons:
                          type: integer
                          description: This field consists of the available number of coupons added to the coupon list.
                        callback_url:
                          type: string
                          description: This field consists of the callback URL.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /coupon-list/{coupon_list_id}/files/{coupon_file_id}:
    get:
      tags:
        - Coupon Files
      summary: Fetch a Coupon File from Coupon List
      operationId: fetchCouponFile
      description: |
        This API retrieves the details of a particular coupon file added to a given coupon list. This includes information such as file status, the number of added coupons, and the file addition date.
      x-mint:
        content: |
          <Note>
            **Information**
            
            There is no request body or content to send for this request except for headers.
          </Note>

          #### Rate Limit
          You can fetch 10,000 coupon files from a coupon list per day.
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
        - $ref: '#/components/parameters/CouponFileIdPath'
      responses:
        '200':
          description: |
            Success
            Indicates that the request was successful and the coupon file was fetched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  coupon_list_id:
                    type: string
                    description: This field contains the coupon list ID from which you fetched the coupon file.
                  name:
                    type: string
                    description: This field contains the coupon file name.
                  status:
                    type: string
                    description: |
                      This field shows one of the following statuses of the fetched coupon file:
                      * PENDING
                  file_url:
                    type: string
                    description: This field consists of the file path of the coupon list.
                  created_by:
                    type: string
                    description: This field consists of the name of the subscriber who uploaded the coupon file.
                  created_at:
                    type: string
                    description: This field consists of the date and time the coupon file was created.
                  updated_at:
                    type: string
                    description: This field consists of the date and time of the most recent update to the coupon file.
                  _id:
                    type: string
                    description: This field contains the unique ID corresponding to a successful coupon file fetch request. This ID is also used to update and archive coupon files from the coupon list.
                  added_coupons:
                    type: integer
                    description: This field consists of the available number of coupons added to the coupon list.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "bad-request"
                  message: "Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Please verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."
    delete:
      tags:
        - Coupon Files
      summary: Delete a Coupon File from the Coupon List
      operationId: deleteCouponFile
      description: |
        This API removes a specific coupon file from a coupon list. It is useful in scenarios where a test file or incorrect file is inadvertently uploaded, thereby ensuring the accuracy and effectiveness of your coupon list management.
      x-mint:
        content: |
          <Note>
            **Information**
            
            There is no request body or content to send for this request except for headers.
          </Note>

          #### Rate Limit
          You can delete:
          * 5 coupon files per minute or
          * 50 coupon files per day
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
        - $ref: '#/components/parameters/CouponFileIdPath'
      responses:
        '204':
          description: |
            Success (No content)
            The request is successful, and the coupon file is deleted.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "invalid-request"
                  message: "The requested JSON is incorrect. Please verify and try again."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Please verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."

  /coupon-list/{coupon_list_id}/usage-report:
    post:
      tags:
        - Reports
      summary: Generate Usage Report
      operationId: generateUsageReport
      description: |
        This API produces a detailed usage report for a specific coupon list, providing details on which user received which coupon from which locale or variation of which campaign at what time. After it is generated, this report is delivered directly to the requested email addresses. Using this API, you can conduct a comprehensive analysis of critical data and coupon usage trends efficiently.
      x-mint:
        content: |
          #### Rate Limit
          You can generate:
          * 5 usage reports of coupon list per minute or
          * 50 usage reports of coupon list per day
      parameters:
        - $ref: '#/components/parameters/AppKeyHeader'
        - $ref: '#/components/parameters/CouponListIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [start_date, end_date, email_subscribers]
              properties:
                start_date:
                  type: string
                  format: date
                  description: This field consists of the start date of the coupon list usage report in `yyyy-mm-dd` format.
                end_date:
                  type: string
                  format: date
                  description: This field consists of the end date of the coupon list usage report in `yyyy-mm-dd` format.
                email_subscribers:
                  type: array
                  items:
                    type: string
                    format: email
                  description: This field consists of the email address of the coupon list subscribers who will receive the report.
            examples: {}
      responses:
        '200':
          description: |
            Success
            Indicates that the request is successful and the coupon list usage report request is accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The following is the success message indicating the report is being processed.
              example:
                message: "The usage report for the {{coupon list name}} coupons is being processed and will be sent to email alert subscribers shortly."
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                start_date_invalid:
                  summary: Start Date Invalid
                  value:
                    error:
                      code: "invalid-request"
                      message: "The start date cannot be earlier than the coupon list creation date. Please verify your dates and try again."
                end_date_invalid:
                  summary: End Date Invalid
                  value:
                    error:
                      code: "invalid-request"
                      message: "The end date cannot be set in the future. Please verify the dates and try again."
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-unauthenticated"
                  message: "Your request is unauthorized. Please verify your credentials and try again."
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "request-forbidden"
                  message: "Your account does not have access to the Coupon Management features. Please contact the MoEngage team for further assistance."
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "coupon-list-not-found"
                  message: "The specified coupon list ID was not found. Please verify the ID and try again."
        '429':
          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.
          headers:
            x-ratelimit-limit:
              schema:
                type: integer
              description: The maximum number of requests that the consumer is permitted to make in a given time window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: The number of requests remaining in the current rate limit window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: The time at which the current rate limit window resets in UTC epoch seconds.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: "unexpected-error"
                  message: "Something went wrong with your request. Please contact the MoEngage team for further assistance."

components:
  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).
  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
    CouponListIdPath:
      name: coupon_list_id
      in: path
      required: true
      description: The unique identifier for the coupon list.
      schema:
        type: string
    CouponFileIdPath:
      name: coupon_file_id
      in: path
      required: true
      description: The unique identifier for the coupon file.
      schema:
        type: string
  schemas:
    AlertConditions:
      type: object
      description: Configuration for various alert triggers.
      properties:
        success_alert: 
          type: boolean
          description: Indicates whether to send an alert on success.
        failure_alert: 
          type: boolean
          description: Indicates whether to send an alert on failure.
        coupon_shortage_alert:
          type: object
          description: Configuration for the coupon shortage alert.
          properties: 
            alert: 
              type: boolean
              description: Indicates whether to enable the coupon shortage alert.
            threshold_count: 
              type: integer
              description: The minimum count of coupons remaining to trigger the alert.
        expiry_alert:
          type: object
          description: Configuration for the expiry alert.
          properties: 
            alert: 
              type: boolean
              description: Indicates whether to enable the expiry alert.
            days_before: 
              type: integer 
              description: Number of days before expiry to trigger the alert.
    CreateCouponListRequest:
      type: object
      required: [name, label, expires_at, created_by]
      properties:
        name:
          type: string
          description: This field consists of the coupon list's unique name.
        label:
          type: string
          description: This field consists of the label name for the coupon list.
        expires_at:
          type: string
          format: date
          description: This field consists of the date the coupon list expires in yyyy-mm-dd format.
        email_alert_subscribers:
          type: array
          items: { type: string, format: email }
          description: This field consists of the email address of the coupon list subscriber. The subscriber will receive all the alerts on the coupon list in the email provided in this field.
        created_by:
          type: string
          description: This field consists of the user name who requests to create the coupon list.
        alert_conditions:
          $ref: '#/components/schemas/AlertConditions'
          description: This object contains the details and types of alert conditions.
    UpdateCouponListRequest:
      type: object
      properties:
        name: { type: string }
        expires_at: { type: string, format: date }
        email_alert_subscribers: { type: array, items: { type: string, format: email } }
        alert_conditions: { $ref: '#/components/schemas/AlertConditions' }
    CouponList:
      type: object
      properties:
        _id: { type: string }
        name: { type: string }
        label: { type: string }
        expires_at: { type: string, format: date-time }
        status: { type: string, enum: [ACTIVE, EXPIRED, ARCHIVED] }
        total_coupons: { type: integer }
        available_coupons: { type: integer }
    UploadCouponFileRequest:
      type: object
      required: [file_url]
      properties:
        name: { type: string }
        file_url: { type: string, format: url }
        file_url_auth_username: { type: string }
        file_url_auth_password: { type: string }
        created_by: { type: string }
        callback_url: { type: string, format: url }
    CouponFile:
      type: object
      properties:
        _id: { type: string }
        name: { type: string }
        status: { type: string }
        added_coupons: { type: integer }
        file_url: { type: string }
    FetchCouponFilesResponseItem:
      type: object
      description: Representation of a coupon file in the response.
      properties:
        coupon_list_id:
          type: string
          description: This field contains the coupon list ID from which you fetched the coupon files.
        name:
          type: string
          description: This field contains the coupon file name.
        status:
          type: string
          description: |
            This field shows one of the following statuses of the fetched coupon files:
            * PENDING
        file_url:
          type: string
          description: This field consists of the file path of the coupon list.
        created_at:
          type: string
          description: This field consists of the date and time the coupon file was created.
        updated_at:
          type: string
          description: This field consists of the date and time of the most recent update to the coupon file.
        created_by:
          type: string
          description: This field consists of the name of the subscriber who uploaded the coupon file.
        _id:
          type: string
          description: This field contains the unique ID corresponding to a successful coupon file fetch request. This ID is also used to update and archive coupon files from the coupon list.
        added_coupons:
          type: integer
          description: This field consists of the available number of coupons added to the coupon list.
        callback_url:
          type: string
          description: This field consists of the callback URL.
    Error:
      type: object
      properties:
        code:
          type: string
          description: 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.
        message:
          type: string
          description: Along with the error code, a detailed message is also provided in the response, describing the specifics of the request failure and the nature of the error.
    ErrorResponse:
      type: object
      properties:
        error: { $ref: '#/components/schemas/Error' }
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "bad-request"
              message: "Possible issues include duplicates, such as coupon list names, invalid data types, or missing mandatory attributes."
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "request-unauthenticated"
              message: "Your request is unauthorized. Verify your credentials and try again."
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "request-forbidden"
              message: "Your account does not have access to the Coupon Management features. Contact the MoEngage team for further assistance."
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "not-found"
              message: "The requested resource was not found."
    TooManyRequests:
      description: |
        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.
      headers:
        x-ratelimit-limit:
          schema:
            type: integer
          description: The maximum number of requests that the consumer is permitted to make in a given time window.
        x-ratelimit-remaining:
          schema:
            type: integer
          description: The number of requests remaining in the current rate limit window.
        x-ratelimit-reset:
          schema:
            type: integer
          description: The time at which the current rate limit window resets in UTC epoch seconds.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "unexpected-error"
              message: "Something went wrong with your request. Contact the MoEngage team for further assistance."
security:
  - basicAuth: []