--- title: Flexible coupons and promotion codes subtitle: Add discounts to subscriptions and subscription items using coupons and promotion codes. route: /billing/subscriptions/coupons --- # Flexible coupons and promotion codes Add discounts to subscriptions and subscription items 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 one or more discounts to every *invoice*, a specific invoice, or for a certain duration of time * Apply one or more discounts to every subscription a customer has or to specific subscriptions * Apply one or more discounts to specific subscription items * Reduce invoice amounts by a percentage or a flat amount 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](https://docs.stripe.com/payments/checkout/discounts.md). ## 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](https://docs.stripe.com/api/coupons/create.md): 1. In the Dashboard, open the [Products](https://dashboard.stripe.com/test/products?active=true) page. 1. Click **Coupons**. 1. Click **+New**. 1. In the **Create a coupon** dialog, enter the coupon’s parameters. 1. 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** | 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](https://docs.stripe.com/products-prices/pricing-models.md#multicurrency). | | **Apply to specific products** | Limits the type of items that the coupon can apply to. | | **Duration** | Indicates how long the coupon is valid for. | | **Redemption limits** | Allows you to limit when a customer can redeem the coupon and the number of times a coupon can be redeemed. | | **Codes** | Allows you to create [promotion codes](#promotion-codes--promotion-codes) for the coupon. | You can only edit the name of the coupon after creation. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new CouponCreateOptions { Duration = "once", Id = "free-period", PercentOff = 100M }; var service = new CouponService(); Coupon coupon = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.CouponParams{ Duration: stripe.String(string(stripe.CouponDurationOnce)), ID: stripe.String("free-period"), PercentOff: stripe.Float64(100), }; result, err := coupon.New(params); ``` ```java Stripe.apiKey = "<>"; CouponCreateParams params = CouponCreateParams.builder() .setDuration(CouponCreateParams.Duration.ONCE) .setId("free-period") .setPercentOff(new BigDecimal(100)) .build(); Coupon coupon = Coupon.create(params); ``` ```node const stripe = require('stripe')('<>'); const coupon = await stripe.coupons.create({ duration: 'once', id: 'free-period', percent_off: 100, }); ``` ```python import stripe stripe.api_key = "<>" coupon = stripe.Coupon.create( duration="once", id="free-period", percent_off=100, ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $coupon = $stripe->coupons->create([ 'duration' => 'once', 'id' => 'free-period', 'percent_off' => 100, ]); ``` ```ruby Stripe.api_key = '<>' coupon = Stripe::Coupon.create({ duration: 'once', id: 'free-period', percent_off: 100, }) ``` The following table contains coupon parameters. | Setting | Description | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | A unique identifier for the coupon. | | `percent_off` or `amount_off` | The amount that is taken off the subtotal for the duration of the coupon. | | `currency` (if `amount_off` is set) | The three-letter ISO code for the currency of the amount to take off. | | `currency_options` (if `amount_off` is set) | If you sell in multiple currencies, amounts to take off the subtotal for different currencies. Multi-currency coupons follow the same rules as [multi-currency prices](https://docs.stripe.com/products-prices/pricing-models.md#multicurrency). | | `duration` | Indicates how long the coupon is valid for. Values include **once**, **forever**, or **repeating**. | | `max_redemptions` | Maximum number of times a coupon can be redeemed across all customers. | | `redeem_by` | The latest date at which you can apply this coupon to customers. | | `applies_to` | Limits the items in an invoice that the coupon can apply to. | 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. To set the products eligible for discounts, add the relevant product IDs to the `applies_to` hash in the coupon. This list of eligible products also applies to promotion codes associated with the coupon. 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](https://docs.stripe.com/billing/subscriptions/change.md) 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 coupons, create a discount by applying them to a subscription. You can apply the coupon when you create the subscription or by [updating a customer’s existing subscription](https://docs.stripe.com/api.md#update_subscription). 1. In the Dashboard, open the **Billing** page and click **Subscriptions**. 1. Click the relevant subscription. 1. Click **Actions**. 1. Click **Update subscription**. 1. Click **Add coupon**. 1. Select one or more coupons from the dropdown menus and click **Submit**. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>" }, }, Discounts = new List { new SubscriptionDiscountOptions { Coupon = "free-period" }, }, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{Price: stripe.String("<>")}, }, Discounts: []*stripe.SubscriptionDiscountParams{ &stripe.SubscriptionDiscountParams{Coupon: stripe.String("free-period")}, }, }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem(SubscriptionCreateParams.Item.builder().setPrice("<>").build()) .addDiscount(SubscriptionCreateParams.Discount.builder().setCoupon("free-period").build()) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', }, ], discounts: [ { coupon: 'free-period', }, ], }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[{"price": "<>"}], discounts=[{"coupon": "free-period"}], ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [['price' => '<>']], 'discounts' => [['coupon' => 'free-period']], ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [{price: '<>'}], discounts: [{coupon: 'free-period'}], }) ``` 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 coupons to it. ### Apply coupons to Checkout Apply coupons to subscriptions in a Checkout Session by setting the `discounts` parameter in the [API](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-discounts). 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. ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"={{payment_method_type}} \ -d "line_items[][price]"="<>" \ -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" ``` ```ruby <> session = Stripe::Checkout::Session.create({ payment_method_types: ['{{payment_method_type}}'], line_items: [{ price: '<>', quantity: 1, }], mode: 'subscription', discounts: [{ coupon: '{{COUPON_ID}}', }], success_url: 'https://example.com/success', cancel_url: 'https://example.com/cancel', }) ``` ```python <> session = stripe.checkout.Session.create( payment_method_types=['{{payment_method_type}}'], line_items=[{ 'price': '<>', 'quantity': 1, }], mode='subscription', discounts=[{ 'coupon': '{{COUPON_ID}}', }], success_url='https://example.com/success', cancel_url='https://example.com/cancel', ) ``` ```php <> $session = \Stripe\Checkout\Session::create([ 'payment_method_types' => ['{{payment_method_type}}'], 'line_items' => [[ 'price' => '<>', 'quantity' => 1, ]], 'mode' => 'subscription', 'discounts' => [[ 'coupon' => '{{COUPON_ID}}', ]], 'success_url' => 'https://example.com/success', 'cancel_url' => 'https://example.com/cancel', ]); ``` ```java <> SessionCreateParams params = SessionCreateParams.builder() .addPaymentMethodType(SessionCreateParams.PaymentMethodType.CARD) .addLineItem( SessionCreateParams.LineItem.builder() .setPrice("<>") .setQuantity(1L) .build()) .setMode(SessionCreateParams.Mode.SUBSCRIPTION) .addDiscount( SessionCreateParams.Discount.builder() .setCoupon("{{COUPON_ID}}") .build()) .setSuccessUrl("https://example.com/success") .setCancelUrl("https://example.com/cancel") .build(); Session session = Session.create(params); ``` ```javascript <> const session = await stripe.checkout.sessions.create({ payment_method_types: ['{{payment_method_type}}'], line_items: [{ price: '<>', quantity: 1, }], mode: 'subscription', discounts: [{ coupon: '{{COUPON_ID}}', }], success_url: 'https://example.com/success', cancel_url: 'https://example.com/cancel', }); ``` ```go <> params := &stripe.CheckoutSessionParams{ PaymentMethodTypes: stripe.StringSlice([]string{ "{{payment_method_type}}", }), LineItems: []*stripe.CheckoutSessionLineItemParams{ &stripe.CheckoutSessionLineItemParams{ Price: stripe.String("<>"), Quantity: stripe.Int64(1), }, }, Mode: stripe.String("subscription"), Discounts: []*stripe.CheckoutSessionDiscountParams{ &stripe.CheckoutSessionDiscountParams{ Coupon: stripe.String("{{COUPON_ID}}"), }, }, SuccessURL: stripe.String("https://example.com/success"), CancelURL: stripe.String("https://example.com/cancel"), } session, _ := session.New(params) ``` ```dotnet <> var options = new SessionCreateOptions { PaymentMethodTypes = new List { "{{payment_method_type}}", }, LineItems = new List { new SessionLineItemOptions { Price = "<>", Quantity = 1, }, }, Mode = "subscription", Discounts = new List { new SessionDiscountOptions { Coupon = "{{COUPON_ID}}", }, }, SuccessUrl = "https://example.com/success", CancelUrl = "https://example.com/cancel", }; var service = new SessionService(); var session = service.Create(options); ``` ### Delete coupons You can delete coupons with the Dashboard or the [API](https://docs.stripe.com/api/coupons/delete.md). 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. 1. In the Dashboard, open the [Products](https://dashboard.stripe.com/test/products?active=true) page. 1. Click **Coupons** 1. Click the relevant coupon. 1. Click the overflow menu (⋯). 1. Click **Delete coupon**. ```dotnet StripeConfiguration.ApiKey = "<>"; var service = new CouponService(); Coupon deleted = service.Delete("free-period"); ``` ```go stripe.Key = "<>" params := &stripe.CouponParams{}; result, err := coupon.Del("free-period", params); ``` ```java Stripe.apiKey = "<>"; Coupon resource = Coupon.retrieve("free-period"); Coupon coupon = resource.delete(); ``` ```node const stripe = require('stripe')('<>'); const deleted = await stripe.coupons.del('free-period'); ``` ```python import stripe stripe.api_key = "<>" deleted = stripe.Coupon.delete("free-period") ``` ```php $stripe = new \Stripe\StripeClient('<>'); $deleted = $stripe->coupons->delete('free-period', []); ``` ```ruby Stripe.api_key = '<>' deleted = Stripe::Coupon.delete('free-period') ``` ### Coupon duration A coupon’s duration indicates how long the redeemed [discount](https://docs.stripe.com/api/.md#discounts) 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. For example, FALLPROMO and SPRINGPROMO can both point to a single 25% off coupon. 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. 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: * [Customer objects](https://docs.stripe.com/api/customers/object.md) * [Subscription Item objects](https://docs.stripe.com/api/subscription_items/object.md) * [Invoice Item objects](https://docs.stripe.com/api/subscription_items/object.md) * [Subscriptions objects](https://docs.stripe.com/api/subscriptions/object.md) when you make an update * Future phases on [Subscription Schedule objects](https://docs.stripe.com/api/subscription_schedules/object.md) ### Create promotion codes You can create a promotion code in the Dashboard when you [create a coupon](#create-coupons--create-coupons). 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](#inactive-promotions--inactivate) it, and then create a new promotion code with the same **Code**. 1. In the Dashboard on the [Create a coupon](https://dashboard.stripe.com/test/coupons/create) page, click the **Use customer-facing coupon codes** button. 1. 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. 1. Select requirements for the promotion code. For example, you can restrict the coupon to only being valid on first-time orders. 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 `code: NEWUSER`, inactivate it by passing `active: false`, and then create a new promotion code with `code: NEWUSER`. To create a [promotion code](https://docs.stripe.com/api/promotion_codes.md), specify an existing `coupon` and any restrictions (for example, limiting to a specific `customer`). If you have a specific code that you want to give to your customer (for example, `FALL25OFF`), set the `code`. If you leave this field blank, Stripe generates a random `code` for you. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new PromotionCodeCreateOptions { Coupon = "ZQO00CcH", Code = "ALICE20", Customer = "<>", }; var service = new PromotionCodeService(); PromotionCode promotionCode = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.PromotionCodeParams{ Coupon: stripe.String("ZQO00CcH"), Code: stripe.String("ALICE20"), Customer: stripe.String("<>"), }; result, err := promotioncode.New(params); ``` ```java Stripe.apiKey = "<>"; PromotionCodeCreateParams params = PromotionCodeCreateParams.builder() .setCoupon("ZQO00CcH") .setCode("ALICE20") .setCustomer("<>") .build(); PromotionCode promotionCode = PromotionCode.create(params); ``` ```node const stripe = require('stripe')('<>'); const promotionCode = await stripe.promotionCodes.create({ coupon: 'ZQO00CcH', code: 'ALICE20', customer: '<>', }); ``` ```python import stripe stripe.api_key = "<>" promotion_code = stripe.PromotionCode.create( coupon="ZQO00CcH", code="ALICE20", customer="<>", ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $promotionCode = $stripe->promotionCodes->create([ 'coupon' => 'ZQO00CcH', 'code' => 'ALICE20', 'customer' => '<>', ]); ``` ```ruby Stripe.api_key = '<>' promotion_code = Stripe::PromotionCode.create({ coupon: 'ZQO00CcH', code: 'ALICE20', customer: '<>', }) ``` When you create a promotion code, it inherits the configuration of the associated coupon. ### Promotion code configurations 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: 1. On the [Create a coupon](https://dashboard.stripe.com/test/coupons/create) page, select **Limit to a specific customer**. 1. Select the relevant customer. If you don’t specify a customer, any customer can redeem the promotion code. To limit a promotion code to a particular customer, specify a `customer` when you create the promotion code. 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](https://dashboard.stripe.com/test/coupons/create) page, select **Eligible for first-time order only**. Limit the promotion code to first time customers with the `first_time_transaction` parameter of the `restrictions` attribute. If the `customer` isn’t defined or if a defined `customer` has no prior payments or non-void invoices, it is considered a first time transaction. ### Set a minimum amount To set an minimum amount that is eligible for a promotion code, on the [Create a coupon](https://dashboard.stripe.com/test/coupons/create) 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. With promotion codes, you can set a minimum transaction amount for eligible discount by configuring the `minimum_amount` and the `minimum_amount_currency` properties. Since promotion code restrictions are checked at redemption time, the minimum transaction amount only applies to the initial payment for a subscription. If you sell in multiple currencies, set the minimum transaction amount for different currencies by configuring the `currency_options` property. ### Customize expirations To set an expiration date for a promotion code, on the [Create a coupon](https://dashboard.stripe.com/test/coupons/create) 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. Set an expiration date on the promotion code using `expires_at`. If the underlying coupon already has `redeem_by` set, then the promotion code’s expiration date can’t be later than the coupon’s. If `promotion_code[expires_at]` isn’t specified, the coupon’s `redeem_by` automatically populates `expires_at`. * 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. You would set `coupon[redeem_by]` to one year from now, and set each `promotion_code[expires_at]` 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](https://dashboard.stripe.com/test/coupons/create) 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. Limit the number of redemptions by using `max_redemptions`, which works similarly to coupons. If the underlying coupon already has `max_redemptions` set, then the promotion code’s `max_redemptions` can’t be greater than the coupon’s. ### Deactivate promotion codes To deactivate a promotion code, doing the following steps: 1. In the Dashboard, open the [Products](https://dashboard.stripe.com/test/products?active=true) page. 1. Click **Coupons**. 1. Click the coupon whose promotion code you want to deactivate. 1. In the relevant promotion code row, click the overflow menu (⋯). 1. 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. Set whether a promotion code is currently redeemable by using the `active` parameter. 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 `max_redemptions` or `expires_at`, it becomes permanently inactive. These promotion codes can’t be reactivated. ### Apply promotion codes to subscriptions After you create a promotion code, redeem a discount by applying the promotion code to a subscription. You can apply promotion codes two ways: * When you [create a subscription](https://docs.stripe.com/api.md#create_subscription) * When you [update a customer’s existing subscription](https://docs.stripe.com/api.md#update_subscription) 1. In the Dashboard, go to **Billing** > **Subscriptions**. 1. Click the relevant subscription. 1. Click **Actions** > **Update subscription** > **Add coupon**. 1. Click a promotion code from the dropdown menu and click **Submit**. 1. [List](https://docs.stripe.com/api/promotion_codes/list.md) the promotion codes and use the [code](https://docs.stripe.com/api/promotion_codes/list.md#list_promotion_code-code) from your Customer as a filter to [retrieve](https://docs.stripe.com/api/promotion_codes/retrieve.md) the [promotion code ID](https://docs.stripe.com/api/promotion_codes/object.md#promotion_code_object-id). 1. To apply the promotion code, use the promotion code ID in the following API call: ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>" }, }, Discounts = new List { new SubscriptionDiscountOptions { PromotionCode = "<>" }, }, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{Price: stripe.String("<>")}, }, Discounts: []*stripe.SubscriptionDiscountParams{ &stripe.SubscriptionDiscountParams{PromotionCode: stripe.String("<>")}, }, }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem(SubscriptionCreateParams.Item.builder().setPrice("<>").build()) .addDiscount( SubscriptionCreateParams.Discount.builder().setPromotionCode("<>").build() ) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', }, ], discounts: [ { promotion_code: '<>', }, ], }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[{"price": "<>"}], discounts=[{"promotion_code": "<>"}], ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [['price' => '<>']], 'discounts' => [['promotion_code' => '<>']], ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [{price: '<>'}], discounts: [{promotion_code: '<>'}], }) ``` ### Add promotion codes to Checkout Enable promotion codes with the API by setting the [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-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](images/billing/subscriptions/promo_code_checkout.png) Promotion code field at checkout ## Stackable coupons and promotion codes You can add multiple coupons, promotion codes, or redeemed [discounts](https://docs.stripe.com/api/.md#discounts) to a customer’s list of charges. You can do this when [creating a subscription](https://docs.stripe.com/api.md#create_subscription) or by [updating a customer’s existing subscription](https://docs.stripe.com/api.md#update_subscription). We support multiple discounts on both subscriptions and subscription items. When you create a subscription with stackable discounts, each discount applies in order to all items on the subscription. The order of the discounts is important if you use both `amount_off` and `percent_off`. For example, the following stacked discounts apply differently: - 20% off _then_ $5 off - $5 off _then_ 20% off 1. In the Dashboard, go to **Billing** > **Subscriptions**. 1. Click the relevant subscription. 1. Click **Actions** > **Update subscription** > **Add coupon**. 1. Click coupons from the dropdown menus and click **Submit**. 1. Click the relevant product. 1. Click **Add coupons**. 1. Click coupons from the dropdown menus and click **Submit**. ```dotnet StripeConfiguration.ApiKey = "<>"; var options = new SubscriptionCreateOptions { Customer = "<>", Items = new List { new SubscriptionItemOptions { Price = "<>", Discounts = new List { new SubscriptionItemDiscountOptions { Coupon = "item-coupon" }, new SubscriptionItemDiscountOptions { PromotionCode = "item-promo" }, }, }, }, Discounts = new List { new SubscriptionDiscountOptions { Coupon = "sub-coupon" }, new SubscriptionDiscountOptions { PromotionCode = "sub-promo" }, }, }; var service = new SubscriptionService(); Subscription subscription = service.Create(options); ``` ```go stripe.Key = "<>" params := &stripe.SubscriptionParams{ Customer: stripe.String("<>"), Items: []*stripe.SubscriptionItemsParams{ &stripe.SubscriptionItemsParams{ Price: stripe.String("<>"), Discounts: []*stripe.SubscriptionItemDiscountParams{ &stripe.SubscriptionItemDiscountParams{Coupon: stripe.String("item-coupon")}, &stripe.SubscriptionItemDiscountParams{PromotionCode: stripe.String("item-promo")}, }, }, }, Discounts: []*stripe.SubscriptionDiscountParams{ &stripe.SubscriptionDiscountParams{Coupon: stripe.String("sub-coupon")}, &stripe.SubscriptionDiscountParams{PromotionCode: stripe.String("sub-promo")}, }, }; result, err := subscription.New(params); ``` ```java Stripe.apiKey = "<>"; SubscriptionCreateParams params = SubscriptionCreateParams.builder() .setCustomer("<>") .addItem( SubscriptionCreateParams.Item.builder() .setPrice("<>") .addDiscount( SubscriptionCreateParams.Item.Discount.builder().setCoupon("item-coupon").build() ) .addDiscount( SubscriptionCreateParams.Item.Discount.builder().setPromotionCode("item-promo").build() ) .build() ) .addDiscount(SubscriptionCreateParams.Discount.builder().setCoupon("sub-coupon").build()) .addDiscount(SubscriptionCreateParams.Discount.builder().setPromotionCode("sub-promo").build()) .build(); Subscription subscription = Subscription.create(params); ``` ```node const stripe = require('stripe')('<>'); const subscription = await stripe.subscriptions.create({ customer: '<>', items: [ { price: '<>', discounts: [ { coupon: 'item-coupon', }, { promotion_code: 'item-promo', }, ], }, ], discounts: [ { coupon: 'sub-coupon', }, { promotion_code: 'sub-promo', }, ], }); ``` ```python import stripe stripe.api_key = "<>" subscription = stripe.Subscription.create( customer="<>", items=[ { "price": "<>", "discounts": [{"coupon": "item-coupon"}, {"promotion_code": "item-promo"}], }, ], discounts=[{"coupon": "sub-coupon"}, {"promotion_code": "sub-promo"}], ) ``` ```php $stripe = new \Stripe\StripeClient('<>'); $subscription = $stripe->subscriptions->create([ 'customer' => '<>', 'items' => [ [ 'price' => '<>', 'discounts' => [['coupon' => 'item-coupon'], ['promotion_code' => 'item-promo']], ], ], 'discounts' => [['coupon' => 'sub-coupon'], ['promotion_code' => 'sub-promo']], ]); ``` ```ruby Stripe.api_key = '<>' subscription = Stripe::Subscription.create({ customer: '<>', items: [ { price: '<>', discounts: [{coupon: 'item-coupon'}, {promotion_code: 'item-promo'}], }, ], discounts: [{coupon: 'sub-coupon'}, {promotion_code: 'sub-promo'}], }) ``` You can start using the new `discounts` parameter on any subscription. We automatically clear out the singular `discount` field when `discounts` with more than one entry is passed in an update. ### Restrictions There are some restrictions to using multiple discounts. * You can set up to 20 entries in the `discounts` parameter. * Each entry in `discounts` has to be unique. * You can not pass in a coupon and a promotion code created from the same coupon. * You can not pass in a coupon and a discount that is generated from the same coupon. * Redeemed discounts must already be attached to the customer or subscription that you’re updating. ### Update a subscription You don’t need to set `discounts` if you don’t intend to make changes to existing discounts. When updating `discounts`, you need to pass in any previously set `coupon`, `promotion_code` or `discount` you want to keep on the subscription. Pass `discounts = ""` to clear all discounts from the subscription. When a subscription has no discounts, the customer-level discount, if any, applies to invoices. If you have already set more than one discount on a subscription with the new `discounts` parameter, you can not update the subscription with the deprecated `coupon` or `promotion_code` parameter. Similarly, you can not update a schedule’s phases with the deprecated `coupon` or `promotion_code` parameter if you have set more than one discount on a prior phase. Updating `discounts` does not incur prorations or generate an invoice on its own. The new discounts are applied the next time the subscription creates an invoice. ## 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](https://docs.stripe.com/api.md#customer_object-balance) to the customer. * Add negative [invoice items](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items). * Add a [second price](https://docs.stripe.com/products-prices/manage-prices.md#create-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. ## See Also * [Changing subscriptions](https://docs.stripe.com/billing/subscriptions/change.md) * [Working with invoices](https://docs.stripe.com/billing/invoices/subscription.md) * [Coupons API](https://docs.stripe.com/api.md#coupons) * [Promotion codes API](https://docs.stripe.com/api.md#promotion_codes)