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

# Coupon Management Overview

> Programmatically manage unique coupon lists, upload coupon codes, and generate usage reports within the MoEngage system.

## Overview

The MoEngage Coupon Management API allows you to organize and distribute unique, single-use coupon codes at scale. Use these endpoints to automate the lifecycle of coupon lists—from creation and file uploads to activation, archival, and detailed usage reporting.

<Info>
  Authentication is handled via **Basic Auth**. Use your **Workspace ID** as the username and your **API Key** as the password.
</Info>

## Coupon API Endpoints

The Coupon Management API is categorized into three functional areas:

### Coupon Lists (Metadata & Status)

* [Create a Coupon List](https://moengage.mintlify.app/api/coupon-lists/create-a-coupon-list) - Define a new category for unique codes.
* [Fetch All Coupon Lists](https://moengage.mintlify.app/api/coupon-lists/fetch-all-coupon-lists) - Retrieve a list of active or archived coupon containers.
* [Fetch Coupon List Details](https://moengage.mintlify.app/api/coupon-lists/fetch-coupon-list-details) - Get real-time counts of available vs. total coupons.
* [Update a Coupon List](https://moengage.mintlify.app/api/coupon-lists/update-a-coupon-list) - Modify names, expiry dates, or alert settings.
* [Activate Coupon List](https://moengage.mintlify.app/api/coupon-lists/activate-coupon-list) - Reactivate archived lists with a new expiry date.
* [Archive a Coupon List](https://moengage.mintlify.app/api/coupon-lists/archive-a-coupon-list) - Transition a list to inactive and delete associated codes.

### Coupon Files (Inventory Management)

* [Upload Coupon File](https://moengage.mintlify.app/api/coupon-files/upload-a-coupon-file-to-the-coupon-list) - Populate a list via a hosted file URL.
* [Fetch All Coupon Files](https://moengage.mintlify.app/api/coupon-files/fetch-all-coupon-files-from-coupon-list) - Track the status of all uploaded batches.
* [Fetch a Coupon File](https://moengage.mintlify.app/api/coupon-files/fetch-a-coupon-file-from-coupon-list) - Check the processing status (e.g., PENDING) of a specific file.
* [Delete a Coupon File](https://moengage.mintlify.app/api/coupon-files/delete-a-coupon-file-from-the-coupon-list) - Remove specific batches (useful for correcting upload errors).

### Reports

* [Generate Usage Report](https://moengage.mintlify.app/api/reports/generate-usage-report) - Request a CSV report sent via email detailing which user received which code.

## Rate Limits & Constraints

| Operation Type          | Daily Limit           | Burst Limit        |
| :---------------------- | :-------------------- | :----------------- |
| **Create Coupon List**  | 100 lists / day       | -                  |
| **Fetch/Search Lists**  | 10,000 requests / day | -                  |
| **Upload Coupon Files** | 50 files / day        | 5 files / minute   |
| **Delete Coupon Files** | 50 files / day        | 5 files / minute   |
| **Generate Reports**    | 50 reports / day      | 5 reports / minute |

## Notes

<Note>
  **Payload Limits:**

  * Manual uploads are limited to **64 MB**.
  * URL-based uploads are limited to **100 MB**.
  * Each coupon list can hold a maximum of **100 million** codes.

  **Initial Setup:** 

  * Creating a coupon list only creates the "container." You must use the **Upload Coupon File API** to add actual codes before the list can be used in campaigns.

  **Archival Impact:** 

  * When you archive a list, all coupon codes within that list are **permanently deleted**. Campaigns relying on this list will immediately stop being able to allocate codes.
</Note>

## Postman Collections

We have made it easy for you to test the APIs. Click [here](https://www.postman.com/moengage-dev/api-docs/collection/y1e45ee/moengage-coupon-management) to view our official Postman collections.