Discounts
Coupons, promotion codes and the discounts they become. A coupon is a percent or amount off for one, several or every billing period; promotion codes are what customers type; a discount is a coupon applied to a customer or subscription, with dates.
Discounts have three parts, all per brand and mode:
- a coupon says what is taken off and for how long, such as "50% off the monthly price for 3 billing periods";
- a promotion code is what a customer types at checkout to get a coupon, such as
LAUNCH50, with its own restrictions; - a discount is a coupon applied to a customer or to one subscription, with the dates it applies between.
Tax is always computed on the discounted amount.
Coupons
A coupon has exactly one of:
- a percent off, as
percentOffPpmin parts per million:"500000"is 50%,"1000000"is 100%; - an amount off, such as €10.00 per invoice, in whole minor units of its currency. It applies only to invoices in that currency.
Its duration is once, repeating (for durationInPeriods billing periods, 1 to 120) or forever. Periods count on the subscription's billing schedule, from the first renewal date at or after the discount starts: a once coupon applied when a subscription starts discounts its first invoice; applied in the middle of a period, it discounts the next renewal.
Optionally, a coupon is limited to some products or prices (appliesTo): only invoice lines of those products or prices are discounted. Limiting it to a price lets an offer cover the monthly fee of a plan but not its yearly price or its usage.
Limits on new redemptions:
maxRedemptions: how many times it can be redeemed in total;redeemBy: no new redemptions from this date on.
Discounts already applied keep running when a coupon reaches a limit or is archived.
Fixed once used
Once a discount uses a coupon, or a redemption is counted, what it gives can't change: its percent or amount, duration, product and price limits, maxRedemptions and redeemBy stay as they were, so every customer keeps what they were promised. The coupon's view says used: true. Its name, metadata and status can still change. To offer different terms, create a new coupon and archive the old one.
Coupons are never deleted. Archiving one stops new redemptions, directly or through its promotion codes. The view's valid says whether it can be redeemed right now: active, before redeemBy and below maxRedemptions.
Promotion codes
A promotion code is a customer-facing string for a coupon: 3 to 50 letters, digits, - or _. Codes are case-insensitive (launch50 and LAUNCH50 are the same code), unique in the brand and mode, and never reused: an archived code keeps its code, so an old code can't suddenly give a different offer.
A code can have restrictions:
| Restriction | The code works only when… |
|---|---|
firstTimeOnly | the customer has no earlier successful payment or paid invoice in this brand. |
minimumAmount | the purchase before discounts reaches this amount, in the same currency. |
customerId | the customer is this customer. |
expiresAt | it is used before this moment. |
maxRedemptions | it was redeemed fewer times than this (the coupon's own limit applies as well). |
When a fact isn't known, the code is refused: a code with a minimum needs the purchase amount, and a customer's code or a first-time code needs the customer. A refused code returns promotion_code_not_redeemable with details.reason, so checkout can tell the customer why. A code and its restrictions can't change; archive it and create another.
To look a code up the way a customer typed it, list promotion codes with code, for example GET /api/v1/promotion_codes?code=launch50.
Discounts
Applying a coupon (directly, or through a promotion code at checkout) creates a discount: the coupon, the code used, the customer, the subscription if any, and its window from start to end. It applies to an invoice dated from start up to, but not including, end; a forever discount has no end.
- A subscription's own discounts apply to its invoices. When it has none, the customer's customer-level discounts apply instead.
- Several discounts can stack: amount-off discounts first, then percent-off, and a line never goes below zero.
- The same coupon can't be applied twice to one subscription (or customer) while its discount is running.
Ending a discount (DELETE /api/v1/discounts/{id}) stops it applying from now on; a discount scheduled to start later never starts. Invoices already issued keep their discount.
Counting redemptions
A redemption is counted when the payment it applies to succeeds, or straight away for free and trial subscriptions. Counting is exact under load: two customers redeeming the last available use at the same moment never both get it. Each discount is counted once, even if a payment notification arrives twice.
Events
| Event | When |
|---|---|
coupon.created, coupon.updated | A coupon was created, renamed, archived or reactivated. |
promotion_code.created, promotion_code.updated | A code was created, archived or reactivated. |
discount.created, discount.deleted | A coupon was applied, or a discount was ended early. |
Counting a redemption doesn't send an event; timesRedeemed shows it.
Coupons in the console
Open a brand, choose Catalog, then Coupons. Owners and admins can change coupons, and developers can in test mode; finance, tax managers, support and viewers can see them.
- Coupons: every coupon, filtered by status, with its discount and redemptions.
- A coupon's page shows its terms and limits and its promotion codes with their restrictions. From there you create codes, archive or reactivate codes, and rename, archive or reactivate the coupon.
Every page names the operation behind it, so you can do the same through the API or an MCP client: see Create a coupon, Create a promotion code and List discounts.