Coupons

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:

Once first invoice only

Inv 1 discountedInv 2 Inv 3 Inv 4

Forever every invoice

Inv 1 discountedInv 2 discountedInv 3 discountedInv 4 discounted

Limited (3 months) a set number of periods

Inv 1 discountedInv 2 discountedInv 3 discountedInv 4

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. To put a coupon on a subscription, see applying a coupon.

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.