Coupons
Coupons are named promo codes — SUMMER25, WELCOME10 — that apply discounts to subscription billing. They are created once in settings, then reused anywhere: on new subscription orders or applied to an existing subscription mid-life.
Create and manage them at Settings → Coupons (owners and admins).
When should I read this?
- Marketing wants a seasonal promo code.
- Sales negotiated "$10 off the first cycle" and you need to make it real.
- A customer asks why their discount stopped — and you need the rules.
Use cases
| Scenario | What you do |
|---|---|
| Summer campaign: 25% off for 3 cycles | Create a percentage coupon, duration Repeating, 3 months; share the code at checkout. |
| Onboarding incentive: $10 off the first invoice | Create a fixed-amount coupon, duration Once. |
| Long-term partner pricing | Duration Forever — the discount rides every cycle until the coupon is archived. |
Create a coupon
| Field | Options | Notes |
|---|---|---|
| Promo Code | Your name for it | Uppercase; this is what customers type (e.g. SUMMER25). |
| Name | Free text | Human-readable label, e.g. "Summer Sale 25% Off". |
| Type | Percentage (%) or Fixed Amount ($) | Fixed amounts are denominated in your base currency. |
| Value | Number | Percent off, or the flat amount off. |
| Duration | Once / Repeating / Forever | Once = one billing cycle; Repeating asks for a duration in months; Forever = every cycle. |
The API additionally supports max redemptions (total use limit) and a valid-until date — both surface on the coupon cards after creation.
Apply a coupon
Two places, two moments:
| Place | Moment | Effect |
|---|---|---|
| Promo Code on a subscription-type order | Checkout | The first invoice carries the discount as a credit line. Invalid or inactive codes are rejected with a clear message. |
| Apply Coupon on a subscription detail page | Any time | The discount applies to future invoices of that subscription. |
Lifecycle and hygiene
- Coupons are archived, not deleted — history and redemption counts stay intact for auditing.
- Each card tracks times redeemed and its limit, so marketing can see uptake at a glance.
- Expired coupons stay visible with an Expired badge; they cannot be newly applied.
**One discount story per order.** A coupon on a subscription order becomes a visible credit line on the first invoice. If you also plan a negotiated line discount, expect both to show — review the invoice preview in the [order](/docs/workspace-guides/orders) before committing.
Common issues
- "This coupon is not active." The coupon was archived or its valid-until date passed; create a fresh code for the new campaign.
- Discount didn't appear on the invoice. Check it was applied to a subscription-type order (the order promo field is subscription-only) and that the invoice is the first one of the subscription.
- Redemptions exceeded expectation. Without a max-redemption limit a code is unlimited — set one for public campaigns.