Coupons Overview

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

​

Cadence

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

​

Validity controls

These fields live on the coupon itself and gate whether a new association can be created. 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.

​

Coupon statuses

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.