---
title: Coupons
description: A code that discounts the bill, by a percentage or a fixed amount.
domain: coupon
status: shipped
visibility: public
last_verified: 2026-07-12
order: 10
---
A coupon has a code that a customer or an operator applies, like `WELCOME20`. It takes money off the invoice, either a percentage or a fixed amount, and you set how long it lasts and how many times it can be redeemed.

## Percentage or fixed amount

A coupon discounts in one of two ways:

- **Percentage:** a percent off the invoice, from 0 to 100. `WELCOME20` at 20% takes a fifth off.
- **Fixed amount:** a set amount off, in a currency. $10 off. A fixed-amount coupon is tied to a currency.

Every discount a coupon produces carries a calculation trace, so you can see exactly how the reduced total was reached.

## What the discount applies to

A coupon discounts one of two things:

- **The whole invoice:** the discount comes off the invoice amount. This is the usual choice.
- **Specific products:** the discount only touches lines for the products you pick. Lines for any other product are billed in full.

Product-scoped coupons let you run an offer on one plan or add-on without discounting everything else on the same invoice.

## How long it lasts

When a coupon is applied to a subscription, its duration decides how many invoices it covers:

```viz coupon-duration
```

| Duration | What it covers |
|---|---|
| Once | The first invoice only. |
| Forever | Every invoice, for as long as the subscription runs. |
| Limited | A set number of months or years, then it stops. |

## Limiting redemptions

You can cap how often a coupon is used:

- **Total redemptions:** the coupon stops working once it has been used this many times across all customers.
- **Per customer:** a single customer can only redeem it up to this many times.

## When a coupon is usable

A coupon can also have a validity window, a start date and an end date. Combined with the caps, a coupon's effective state at any moment is one of:

| State | Meaning |
|---|---|
| Active | Usable now. |
| Future | Its start date has not arrived. |
| Expired | Its end date has passed. |
| Exhausted | Its total redemption cap is used up. |
| Archived | Turned off by hand. |

## In the API

Create a coupon with the `POST /v1/coupons` endpoint, setting the code, the discount, the duration, and any limits. You can list, fetch, archive, and unarchive coupons too. See the [API reference](/reference). To put a coupon on a subscription, see [applying a coupon](/guide/coupons/applying-coupons).

## Edge cases

- **Fixed-amount coupons carry a currency.** A $10-off coupon only makes sense in the currency it was set up for.
- **A code is unique within your organization.** No two coupons share a code.
- **Archiving stops new use but keeps history.** An archived coupon cannot be applied to new subscriptions, but the record of past use stays.