> ## 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. # Create a Coupon List > This API creates single-use coupon codes. You can use this API to create and organize distinct lists for different coupon code categories. **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. #### Rate Limit You can create 100 coupon lists per day. ## OpenAPI ````yaml /api/coupons/coupons.yaml post /coupon-list 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. security: - basicAuth: [] 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 description: > This API creates single-use coupon codes. You can use this API to create and organize distinct lists for different coupon code categories. operationId: createCouponList 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. components: schemas: 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. ErrorResponse: type: object properties: error: $ref: '#/components/schemas/Error' 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. 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. 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). ````