Applying discounts to subscriptions

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).

Creating coupons

Coupons have the following parameters:

• id, a unique identifier for the coupon
• currency
• percent_off or amount_off
• duration, once, forever, or repeating
• max_redemptions
• 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

For 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.

The max_redemptions and 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.

Coupons can be created in the Dashboard or via the API, as shown here:

curl https://api.stripe.com/v1/coupons \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "duration"="once" \
  -d "id"="free-period" \
  -d "percent_off"=100

Discounting subscriptions

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.

curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="cus_4fdAW5ftNQow1a" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f" \
  -d "coupon"="free-period"

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).

Discounting customers

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.

Attach a coupon to a customer when the customer is created, or by updating the customer.

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.

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"

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.

Deleting coupons

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.