Coupon and Promotion Code

A Coupon is a reusable discount definition (percent or fixed amount, with a duration). A Promotion Code is a customer-redeemable shortcode that points at exactly one coupon and adds redemption controls (validity window, redemption cap, first-time-only, minimum amount). You apply a coupon directly when you have one in hand server-side; you accept a promotion code when a customer types one in.

Lifecycle

1. Create the coupon with createCoupon — choose percent_off or amount_off + currency, plus duration (once, repeating, forever). For repeating, set duration_in_months.
2. Optionally create promotion codes with createPromotionCode referencing the coupon_id. The same coupon can back many codes.
3. Validate a code before applying with validatePromotionCode — returns valid, the resolved coupon, and a discount_preview.
4. Apply to a subscription via applySubscriptionDiscount (pass either coupon_id or promotion_code); scope to a single subscription item with subscription_item_id if needed.
5. Remove with removeSubscriptionDiscount to end the discount before its natural expiry. Coupons and promotion codes can be soft-disabled via active: false (updateCoupon / updatePromotionCode) or deleted outright.

Relationships

A PromotionCodeData always points at one CouponData (coupon_id). When applied to a subscription, both surface as a SubscriptionDiscount row referencing coupon_id and/or promotion_code_id. Coupons may be scoped to a subset of products via applies_to_products, in which case only invoice line items whose price_id belongs to one of those products receive the discount.

Fields that matter

• Coupon duration (once | repeating | forever) — controls how many billing cycles the discount applies for. repeating requires duration_in_months.
• Coupon percent_off (number, 0–100) or amount_off (number, smallest currency unit) — exactly one is set; amount_off requires currency.
• Coupon max_redemptions / times_redeemed — global cap across all customers; applies_to_products scopes the discount to specific products.
• Promotion code code (string) — the human-typed token. Case is preserved as stored.
• Promotion code first_time_only (boolean) — restricts to a customer's first redemption against this coupon family.
• Promotion code minimum_amount (number) — the invoice or subscription subtotal that must be reached for the code to apply.

Related

• API reference: Coupons
• API reference: Promotion codes
• Guide: Apply a coupon