Coupons in Stripe provide discounts on recurring charges. Like subscriptions, coupons allow for great flexibility in how you define and use them. They can:
- Apply to every invoice, just one invoice, or for a certain length of time
- Reduce invoices by a percentage or a flat amount
- Apply to every subscription a customer has or only specific ones
You can even define a coupon that must be redeemed by a certain date or is limited to a set number of redemptions (across all of your customers).
Coupons have the following parameters:
id, a unique identifier for the coupon
duration, once, forever, or repeating
redeem_by, the latest date at which this coupon can be applied to customers
applies_to, limits the items in an invoice that the coupon can apply to, but does not add restrictions to subscriptions
duration, when using the value repeating, also specify
duration_in_months as the number of months for which the coupon should repeatedly apply. Otherwise the coupon can be set to apply only to a single invoice or to them all.
redeem_by values apply to the coupon across every customer you have. For example, you can restrict a coupon to the first 50 customers that use it, or you can make a coupon expire by a certain date. If you do the latter, this only impacts when the coupon can be applied to a customer. If you set a coupon to last forever when used by a customer, but have it expire on January 1st, any customer given that coupon will have that coupon’s discount forever, but no new customers can apply the coupon after January 1st.
If a coupon has a
max_redemptions value of 50, it can only be applied among all your customers a total of 50 times, although there’s nothing preventing a single customer from using it multiple times. (You can always use logic on your end to prevent that from occurring.)
You can limit the products that are eligible for discounts using a coupon by adding the product IDs to the
applies_to hash in the Coupon Object. Any promotion codes that map to this coupon are also restricted to this list of eligible products. When adding a coupon with
applies_to to a subscription with no applicable products, a discount of zero is generated.
When making changes to a subscription, any existing discounts are applied when proration is calculated. You cannot discount proration line items further on the invoice that’s generated.
Once you’ve created a coupon, create a discount by applying the coupon to a subscription. You can do this when creating the subscription, as in the following code, or by updating an existing subscription.
If the effect of a coupon means no immediate payment is required, the subscription can be created even if the customer has no stored payment method (e.g. credit card).
You can attach a coupon to a subscription or a customer. A coupon added to a customer applies to all recurring charges for that customer. For this reason, we recommend adding coupons to subscriptions, not customers, unless you want to discount all recurring charges for a customer, even on subscriptions added later.
Using coupons in Checkout
You can apply coupons to subscriptions in a Checkout Session by setting discounts. This coupon overrides any coupon on the customer.
If you’re creating a subscription with an existing customer, any coupon associated with the customer is applied to the subscription’s invoices.
Negative invoice items and customer balances
Although coupons are the most common way to discount a subscription, you can also do so via negative invoice items or by adding a negative customer balance to the customer. Of the two options, we recommend using invoice items, which provide a better paper trail as to what discount was created, when, and why.
You can delete coupons via the Dashboard or the API. However, deleting a coupon does not remove the applicable discount from any subscription or customer. Deleting a coupon does prevent it from being applied to future subscriptions or customers, though.