Applying Discounts to Subscriptions

Reduce the amount charged to a customer by discounting their subscription with a coupon.

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

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

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_BQokikJOvBiI2HlWgH4olfQ2: \
   -d duration=once \
   -d id=free-period \
   -d percent_off=100

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = Stripe::Coupon.create({
    duration: 'once',
    id: 'free-period',
    percent_off: 100,
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

coupon = stripe.Coupon.create(
  duration='once',
  id='free-period',
  percent-off=100,
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$coupon = \Stripe\Coupon::create([
    'duration' => 'once',
    'id' => 'free-period',
    'percent_off' => 100,
]);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> params = new HashMap<>();
params.put("duration", "once");
params.put("id", "free-period");
params.put("percent_off", 100);
Coupon coupon = Coupon.create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

const coupon = stripe.coupons.create({
  duration: 'once',
  id: 'free-period',
  percent_off: 100,
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CouponParams{
  Duration: "once",
  Id: "free-period",
  Percent: 100,
}
free, _ := coupon.New(params)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

var options = new StripeCouponCreateOptions {
    Duration = "once",
    Id = "free-period",
    PercentOff = 100,
};
var service = new StripeCouponService();
StripeCoupon coupon = service.Create(options);

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_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_4fdAW5ftNQow1a \
   -d items[0][plan]=plan_CBb6IXqvTLXp3f \
   -d coupon=free-period

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = Stripe::Subscription.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
    coupon: 'free-period',
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[{'plan': 'plan_CBb6IXqvTLXp3f'}],
  coupon='free-period',
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [['plan' => 'plan_CBb6IXqvTLXp3f']],
    'coupon' => 'free-period',
]);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> item = new HashMap<>();
item.put("plan", "plan_CBb6IXqvTLXp3f");
Map<String, Object> items = new HashMap<>();
items.put("0", item);
Map<String, Object> params = new HashMap<>();
params.put("customer", "cus_4fdAW5ftNQow1a");
params.put("items", items);
params.put("coupon", "free-period");
Subscription subscription = Subscription.create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

const subscription = stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
  coupon: 'free-period',
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

items := []*stripe.SubItemsParams{
  {Plan: "plan_CBb6IXqvTLXp3f",},
}
params := &stripe.SubParams{
  Customer: "cus_4fdAW5ftNQow1a",
  Items: items,
  Coupon: "free-period",
}
subscription, _ := sub.New(params)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

var items = new List<StripeSubscriptionItemOption> {
    new StripeSubscriptionItemOption {PlanId = "plan_CBb6IXqvTLXp3f"}
};
var options = new StripeSubscriptionCreateOptions {
    Items = items,
    Coupon = "free-period",
};
var service = new StripeSubscriptionService();
StripeSubscription subscription = service.Create("cus_4fdAW5ftNQow1a", options);

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 source (e.g., credit card or bank account).

Discounting customers

A coupon can be attached specifically to a subscription or broadly to a customer. A coupon added to a customer applies to all recurring charges for that customer. (Coupons never apply to standalone, nonrecurring charges.) For this reason, we recommend adding coupons to subscriptions, not customers, unless you’re certain you’ll always 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.

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 account 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 (just as deleting a plan does not remove subscriptions to that plan). Deleting a coupon does prevent it from being applied to future subscriptions or customers, though.

Next steps

Now that you understand how to use coupons to create discounts, you may want to check out: