Discounts for subscriptions

Add a discount to a subscription using coupons and promotion codes.

Redeem coupons to apply discounts to the subscriptions you offer. You can also use coupons to create promotion codes to share with your customers. Customers can redeem these promotion codes to apply discounts to their subscriptions.

You can use coupons and promotion codes to:

Apply discounts to every invoice, only one invoice, or for a certain length of time
Reduce invoice amounts by a percentage or a flat amount
Apply discounts to every subscription a customer has or only specific ones

You can also define a coupon that a customer must redeem by a certain date, or that’s limited to a set number of redemptions across all of your customers.

To use discounts for one-time payments, see Add discounts for one-time payments.

Coupons

To apply discounts to a customer or a customer’s charges, redeem coupons into discounts. Learn how to create and manage coupons in the following sections.

Create a coupon

Create coupons in the Dashboard or with the API:

In the Dashboard, open the Products page.
Click Coupons.
Click +New.
In the Create a coupon dialog, enter the coupon’s parameters.
Click Create coupon.

Here are all the settings for coupons.

Setting	Description
Name	The name of the coupon that appears on receipts and invoices.
ID optional	A unique identifier for the coupon in the API. If you leave this field blank, Stripe generates an ID for you.
Type	Determines whether a coupon discounts a subscription by a fixed amount or by a percentage.
Percentage off or Discount amount	Indicates how much the coupon actually discounts. If you sell in multiple currencies, a single coupon can define different discount amounts for different currencies. Multi-currency coupons follow the same rules as multi-currency prices.
Apply to specific products optional	Limits the type of items that the coupon can apply to.
Duration	Indicates how long the coupon is valid for.
Redemption limits optional	Allows you to limit when a customer can redeem the coupon and the number of times a coupon can be redeemed.
Codes optional	Allows you to create promotion codes for the coupon.

You can only edit the name of the coupon after creation.

Set eligible products

To set the products that are eligible for discounts, add the relevant product in the Apply to specific product field. Any promotion codes that are associated with the coupon are also restricted to this list of eligible products.

If you configure a coupon to apply to specific products and a subscription doesn’t have any applicable products, no discount is applied when you add the coupon to the subscription.

When you make changes to a subscription, any existing discounts are applied when proration is calculated. You can’t discount proration line items further on the invoice that’s generated.

Apply coupons to subscriptions

After you’ve created a coupon, create a discount by applying the coupon to a subscription. You can do this when creating the subscription or by updating a customer’s existing subscription.

In the Dashboard, open the Billing page and click Subscriptions.
Click the relevant subscription.
Click Actions.
Click Update subscription.
Click Add coupon.
Click a coupon from the menu and click Submit.

You can still create a subscription when a customer doesn’t have a stored payment method if no immediate payment is required after you apply a coupon to it.

Apply coupons to customers

A coupon that you add to a customer applies to all subscriptions for that customer, including subscriptions added later. Add coupons to subscriptions instead of customers, unless you want to discount all recurring charges for a customer.

In the Dashboard, open the Customers page and select the customer.
Click Actions
Click Apply coupon.
Select a coupon from the drop-down menu and click Submit.

Apply coupons to Checkout

Apply coupons to subscriptions in a Checkout Session by setting the discounts parameter in the API. To create a session with an applied discount, pass the coupon ID in the coupon parameter of the discounts array. 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.

Command Line

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"=card \
  -d "line_items[][price]"={{PRICE_ID}} \
  -d "line_items[][quantity]"=1 \
  -d mode=subscription \
  -d "discounts[][coupon]"="{{COUPON_ID}}" \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Delete coupons

You can delete coupons with the Dashboard or the API.

Deleting a coupon prevents it from being applied to future subscriptions or customers, but it doesn’t remove the discount from any subscription or customer that already has it.

In the Dashboard, open the Products page.
Click Coupons
Click the relevant coupon.
Click the overflow menu ().
Click Delete coupon.

Coupon duration

A coupon’s duration indicates how long the coupon is valid for. For example, a coupon for 50% off with a duration of 4 months applies to all invoices in the 4 month period starting when the coupon is first applied. If a customer applies this coupon to a yearly subscription during the coupon’s 4 month period, the 50% discount applies to the entire yearly subscription. In a monthly subscription, the coupon applies to the first 4 months. For a weekly subscription, a 4 month coupon applies to every invoice in the first 4 months.

If you’re configuring a coupon’s duration in the API, when you use the value repeating you must specify duration_in_months as the number of months that the coupon repeatedly applies to. If you set the duration to once, the coupon applies only to the first invoice. If you set the duration to forever, the coupon applies to all invoices indefinitely.

Redemption limits

Redemption limits apply to the coupon across every customer. For example, if you limit the number of times a coupon can be redeemed to 50, you can apply it to your customers only 50 times. This can be one time each for 50 different customers, one customer 50 times, or multiple customers multiple times until the max of 50 times.

If you set a coupon to last forever when a customer uses it but the coupon has an expiration date, any customer given that coupon will have that coupon’s discount forever. No new customers can apply the coupon after the expiration date.

Promotion codes

Promotion codes are customer-facing codes that you create for coupons. You can share promotion codes directly with your customers to use at checkout.

If you’ve implemented the customer portal and turned on promotion codes, customers can apply a discount when upgrading or downgrading their existing subscriptions in the portal.

Create customer-facing codes that are associated with a single underlying coupon. For example, FALLPROMO and SPRINGPROMO can both point to a single 25% off coupon.

Customize controls and limits on promotion codes by specifying eligible customers, first time orders, minimum order values, expiration dates, and redemption limits.

Restrictions

There are some restrictions to promotion codes.

You can’t apply a promotion code with amount restrictions on the Customer object or on a subscription update API call.
You can’t apply both a promotion code and a coupon at the same time to a subscription or a customer.
It’s not possible to stack two or more promotion codes.

Create promotion codes

You can create a promotion code in the Dashboard when you create a coupon.

The Code is case-insensitive and unique across active promotion codes for any customer. For example:

You can create multiple customer-restricted promotion codes with the same Code, but you can’t reuse that Code for a promotion code that any customer can redeem.
If you create a promotion code that is redeemable by any customer, you can’t create another active promotion code with the same code.
You can create a promotion code with one Code, inactivate it, and then create a new promotion code with the same Code.

In the Dashboard on the Create a coupon page, click the Use customer-facing coupon codes button.
Enter a code. This is the code that a customer enters at checkout to redeem the discount. If you don’t set a code, Stripe generates one for you.
Select requirements for the promotion code. For example, you can restrict the coupon to only being valid on first-time orders.

When you create a promotion code, it inherits the configuration of the associated coupon.

By configuring the promotion code settings, you can customize the following:

Which customers are eligible to use a promotion code
How many times a customer can redeem a promotion code
When a promotion code expires
Set a minimum amount a promotion code can apply to

Limit by customer

To limit a promotion code to a particular customer complete these steps:

On the Create a coupon page, select Limit to a specific customer.
Select the relevant customer. If you don’t specify a customer, any customer can redeem the promotion code.

Limit by first time order

To limit a promotion code to a customer’s first order, on the Create a coupon page, select Eligible for first-time order only.

Set a minimum amount

To set an minimum amount that is eligible for a promotion code, on the Create a coupon page, select Require minimum order value and enter the minimum value.

Because promotion code restrictions are checked at redemption time, the minimum transaction amount only applies to the initial payment for a subscription.

If the coupon supports multiple currencies, the minimum amount can be different per-currency.

Customize expirations

To set an expiration date for a promotion code, on the Create a coupon page, select Add an expiration date and the date and time at which the promotion code expires.

If the underlying coupon already has an expiration date set, then the promotion code’s expiration date can’t be later than the coupon’s.

For example, you might have plans to support a coupon for a year, but you only want it to be redeemable for one week after a customer receives it. To do this, set the coupon’s expiration date to one year from now, and set each the promotion code’s expiration date to one week after it is created.

Limit redemptions

To set the number of times a customer can redeem the promotion code, on the Create a coupon page, select Limit the number of times this code can be redeemed and enter the number.

If the underlying coupon already has a maximum number of times set, then the promotion code’s maximum redemptions can’t be greater than the coupon’s.

Deactivate promotions

To deactivate a promotion code, doing the following steps:

In the Dashboard, open the Products page.
Click Coupons.
Click the coupon whose promotion code you want to deactivate.
In the relevant promotion code row, click the overflow menu ().
Click Archive promotion code.

However, if the underlying coupon for a promotion code becomes invalid, all of its promotion codes become permanently inactive. Similarly, if a promotion code reaches its maximum redemption limit or its expiration date, it becomes permanently inactive. These promotion codes can’t be reactivated.

Add promotion codes to Checkout

Enable promotion codes with the API by setting the allow_promotion_codes parameter in Checkout Sessions. When allow_promotion_codes is enabled on a Checkout Session, Checkout includes a promotion code redemption box for your customers to use.

Promotion code field at checkout

Alternative discount methods

Although coupons are the most common way to discount a subscription, you can also do the following:

Add a negative customer balance to the customer.
Add negative invoice items.
Add a second price that is a cheaper version of a product’s usual price.

Of these methods, negative invoice items provide more detailed information as to what discount was created, when, and why.