Coupons define reusable discount templates you can attach to subscriptions to reduce what a customer is charged. They support percentage, fixed-amount, and usage-credit discounts, with optional scope and time limits.
A coupon is a reusable discount object. You define the discount once, then apply it to one or more subscriptions. The discount is calculated at invoice generation time and appears as a reduction on the relevant line items.
Coupons have two layers of optionality:
SUMMER25) that reference a coupon. Promotion codes let you distribute the same underlying discount through different channels or with different redemption limits.By default, a coupon applies to the full invoice. You can restrict it to specific product categories, products, or product items using the limited_to field. Scoped coupons only reduce charges on matching line items.
Coupons follow the standard resource lifecycle: DRAFT → ACTIVE → INACTIVE → DEPRECATED → ARCHIVED. Only ACTIVE coupons can be redeemed. You must activate a coupon before attaching it to a subscription.
Use the Create a coupon endpoint:
Then activate it:
Navigate to Product catalog → Coupons → Add coupon. Fill in:
Promotion codes are human-readable codes linked to a coupon. Create one when you want to distribute a discount through a campaign, referral link, or self-serve flow. Use the Create a promotion code endpoint:
Promotion codes inherit the coupon’s discount and duration. You can add their own start_at, end_at, and maximum_redemptions to further restrict a specific code without changing the underlying coupon.
Attach a coupon to a subscription schedule using either a coupon ID or a promotion code. You can pass both at the same time if needed. See the Create a pricing plan subscription endpoint:
Or by promotion code:
allow_promotion_codes on the subscription template controls whether customers can self-apply promotion codes. Set to SINGLE to allow one code per subscription, or NONE to disable self-service redemption entirely.Applied coupons appear on the invoice under coupons and promotion_codes, and the discount is reflected on the relevant line items.
Use the Get a list of coupon redemptions endpoint to see which customers have redeemed a coupon:
The number_of_redemptions field on the coupon object tracks the running total.
maximum_redemptions set will stop accepting new attachments once that limit is reached, even if it remains ACTIVE.INACTIVE) does not remove it from existing subscriptions. It only prevents new redemptions.Coupons and promotion codes are managed through the Configuration API: