> ## 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.

# Coupons Overview

> Create percentage or fixed-amount discounts and apply them to subscriptions at the invoice or line-item level.

A coupon is a reusable discount definition. You create it once, then link it to one or more subscriptions via an **association**. Each association can be scoped to a time window and optionally targeted at a specific line item rather than the whole invoice.

## Coupon types

| Type         | Discount field   | Currency required | Example             |
| ------------ | ---------------- | ----------------- | ------------------- |
| `percentage` | `percentage_off` | No                | 15% off the invoice |
| `fixed`      | `amount_off`     | Yes               | \$50 off            |

## Cadence

Cadence controls how many billing cycles the discount repeats within an association's active window.

| Cadence    | Behavior                                                     |
| ---------- | ------------------------------------------------------------ |
| `once`     | Applied to the first invoice of the association period only  |
| `repeated` | Applied for `duration_in_periods` consecutive billing cycles |
| `forever`  | Applied to every invoice for the life of the subscription    |

## Validity controls

These fields live on the coupon itself and gate whether a new association can be created.

| Field             | Purpose                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `redeem_after`    | Earliest timestamp a coupon can be associated to a subscription                                                              |
| `redeem_before`   | Expiry timestamp. Associations cannot be created after this date. Existing associations created before expiry remain active. |
| `max_redemptions` | Maximum total associations allowed across all subscriptions                                                                  |

The `total_redemptions` counter increments when the association is **created**, not when an invoice is generated.

## Coupon scope

**Subscription level**: discount applies to the invoice subtotal (or the running subtotal after earlier coupons have applied).

**Line-item level**: discount applies to a specific price within the invoice before any subscription-level coupons run.

## How multiple coupons apply

When an invoice has both line-item and subscription-level coupons:

1. Line-item coupons apply first, reducing each targeted line item's amount individually.
2. Subscription-level coupons apply next, in association order, each seeing the subtotal left after the previous coupon.
3. Wallet credits are deducted after all coupon discounts.
4. Tax is calculated on `MAX(subtotal - all_discounts, 0)`. Tax is never charged on discounted-away amounts.

<Info>
  Two 20% subscription-level coupons do not produce a 40% total discount. The second coupon applies to the amount remaining after the first. See [Billing Calculation Order](/docs/invoices/billing-calculation-order) for the full worked example.
</Info>

## Coupon statuses

| Status     | Meaning                               |
| ---------- | ------------------------------------- |
| `draft`    | Created but not yet usable            |
| `active`   | Can be associated to subscriptions    |
| `archived` | No longer usable for new associations |

Only `active` coupons pass association validation.

## Quick start

1. [Create a coupon](/docs/product-catalogue/coupons/create) with a type, value, and optional validity window.
2. [Apply it to a subscription](/docs/product-catalogue/coupons/apply-discount-on-subscription) at creation time or via subscription phases for scheduled windows.