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

# Create a Coupon

> Create percentage or fixed-amount discount coupons via API or dashboard.

## Via API

```bash theme={null}
curl -X POST https://api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale",
    "type": "percentage",
    "percentage_off": "15.00",
    "cadence": "once",
    "coupon_code": "SUMMER15",
    "redeem_after": "2025-07-01T00:00:00Z",
    "redeem_before": "2025-08-31T23:59:59Z",
    "max_redemptions": 1000
  }'
```

**Response**

```json theme={null}
{
  "id": "coup_01abc123",
  "name": "Summer Sale",
  "type": "percentage",
  "percentage_off": "15.00",
  "cadence": "once",
  "coupon_code": "SUMMER15",
  "redeem_after": "2025-07-01T00:00:00Z",
  "redeem_before": "2025-08-31T23:59:59Z",
  "max_redemptions": 1000,
  "total_redemptions": 0,
  "status": "active"
}
```

## Request fields

| Field                 | Type           | Required                | Description                                                                                       |
| --------------------- | -------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
| `name`                | string         | Yes                     | Display name shown in the dashboard and invoice details                                           |
| `type`                | string         | Yes                     | `percentage` or `fixed`                                                                           |
| `cadence`             | string         | Yes                     | `once`, `repeated`, or `forever`                                                                  |
| `percentage_off`      | decimal string | When `type=percentage`  | Discount as a percent, e.g. `"15.00"` for 15%                                                     |
| `amount_off`          | decimal string | When `type=fixed`       | Flat discount amount, e.g. `"50.00"`                                                              |
| `currency`            | string         | When `type=fixed`       | ISO currency code, e.g. `"USD"`                                                                   |
| `duration_in_periods` | int            | When `cadence=repeated` | Number of billing cycles the discount applies. Must not be set for other cadences.                |
| `coupon_code`         | string         | No                      | Human-readable code customers can enter to redeem (e.g. `"SUMMER15"`). Auto-generated if omitted. |
| `redeem_after`        | timestamp      | No                      | Earliest time a new association can be created                                                    |
| `redeem_before`       | timestamp      | No                      | Expiry. New associations cannot be created after this time.                                       |
| `max_redemptions`     | int            | No                      | Cap on total associations across all subscriptions                                                |
| `metadata`            | object         | No                      | Key-value pairs for your own tracking                                                             |

## Cadence behaviour

| Cadence    | What happens                                                          |
| ---------- | --------------------------------------------------------------------- |
| `once`     | Discount applies to the first invoice in the association window only  |
| `repeated` | Discount applies for `duration_in_periods` consecutive billing cycles |
| `forever`  | Discount applies to every invoice for the life of the subscription    |

## Fixed-amount coupon

For a fixed dollar amount off, set `type: fixed` and provide both `amount_off` and `currency`:

```bash theme={null}
curl -X POST https://api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Customer Credit",
    "type": "fixed",
    "amount_off": "50.00",
    "currency": "USD",
    "cadence": "once"
  }'
```

## Recurring coupon

To discount multiple billing cycles, use `cadence: repeated` with `duration_in_periods`:

```bash theme={null}
curl -X POST https://api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quarterly Promo",
    "type": "percentage",
    "percentage_off": "20.00",
    "cadence": "repeated",
    "duration_in_periods": 3
  }'
```

This applies a 20% discount for the first 3 billing cycles of each association.

## Manage existing coupons

```bash theme={null}
# List coupons
curl https://api.flexprice.io/v1/coupons \
  -H "x-api-key: <API_KEY>"

# Get a coupon
curl https://api.flexprice.io/v1/coupons/<coupon_id> \
  -H "x-api-key: <API_KEY>"

# Search coupons by status
curl -X POST https://api.flexprice.io/v1/coupons/search \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

# Update a coupon (only name and metadata are updatable)
curl -X PUT https://api.flexprice.io/v1/coupons/<coupon_id> \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer Sale 2025" }'

# Delete a coupon
curl -X DELETE https://api.flexprice.io/v1/coupons/<coupon_id> \
  -H "x-api-key: <API_KEY>"
```

## Via dashboard

Go to **Product Catalog** > **Coupons** > **Create Coupon** and fill in the same fields described above.

## Next step

[Apply the coupon to a subscription](/docs/product-catalogue/coupons/apply-discount-on-subscription) at creation time or post-creation via the subscription modification API.