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.

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 for the full worked example.

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 with a type, value, and optional validity window.
2. Apply it to a subscription at creation time or via subscription phases for scheduled windows.