Applying discounts to a new subscription

We all must have seen promotion codes or discount codes like FLAT5PROMO or FLAT30 when we have purchase things from e-commerce websites. They are used by customers to get a discount on the total invoiced amount on their purchase.

In Stripe, coupons and promotion codes are two distinct entities. Coupons are a discount entity that is responsible for reducing the total invoice amount charged to a customer when they buy a subscription and these are not accessible to customers directly.

Promotion codes are customer-facing entities, that are accessible to customers directly, and they are created on top of coupons. A promotion code can not be created without a coupon.

We know it is a bit confusing, so let's first start by properly understanding what coupons are.

Coupons

Let's say, we want to give a 50% discount to all new customers who will subscribe to our plans mentioned in the Modelling our product and prices in Stripe section on their first subscription. To apply a discount on a subscription we will first need to create coupons in Stripe.

Now, the question is how we can create coupons in Stripe?

Creating coupons

We can create coupons via Stripe Dashboard or Stripe API.

Let's start creating coupon via Dashboard:

We have already registered for the Stripe account. Now, login to Stripe Dashboard and then navigate Coupons page.

Coupons

Click on the Create a test coupon button and enter the details as shown below:

Create a Coupon

We have our first coupon, let's see how we can create promotion codes.

Promotion codes

Promotion codes are customer-facing codes that are created on top of coupons and can be shared directly with our customers.

For instance, we have a customer Oliver who wants to subscribe to our Monthly Standard Plan. Let's see how we can create a promotion code in a Dashboard.

Navigate to coupons Dashboard and click on the First purchase discount coupon.

We will see Promotion Codes section and click on the Add a promotion code button.

Add Promotion Code.

Enter promotion code details as shown below and save it.

Create a Promotion Code

Enabling promotion code in Checkout session

Let's say, we have a customer Oliver who wants to subscribe to our Monthly Standard Plan. We want to give him an option to select a promotion code on the Stripe checkout session page.

To understand how we can enable the selection of promotion code, let's see the API request we are sending to create a checkout session in our application.

1$ curl https://api.stripe.com/v1/checkout/sessions \
2> -u sk_test_51IUPamDdkrcdQOlhs2b...VV2OQeFjRe1004Oahe9N3: \
3> -d "payment_method_types[]"="card" \
4> -d "line_items[0][price_data][unit_amount]"=1900 \
5> -d "line_items[0][price_data][currency]"="usd" \
6> -d "line_items[0][price_data][product]={{PRODUCT_ID}}" \
7> -d "line_items[0][price_data][recurring][interval]=month" \
8> -d "line_items[0][quantity]"=1 \
9> -d "mode"="subscription" \
10> -d "allow_promotion_codes"="true" \
11> -d "success_url"="https://example.com/success" \
12> -d "cancel_url"="https://example.com/cancel"

Now, the question is what this request is doing and what parameters we are using? We need to pass parameter allow_promotion_codes with value true to enable selection of promotion code on the Checkout Page and also we can refer create checkout session API to get more understanding.

When Oliver subscribes, we will enable the selection of promotion code by sending the create checkout session API request as shown above.

Checkout Session with promotion code

Oliver has a promotion code FIRSTSUBSCRIPTIONPROMO that we have created in the Promotion Codes section. Once he enters the promotion code, we will see that the total invoiced is reduced by 50%.

Checkout Session with promotion code applied

After, subscribing successfully Oliver will be charged $9.5 immediately. But for future months he will be charged $19 because the coupon associated with the promotion code FIRSTSUBSCRIPTIONPROMO has a duration once that means coupons is applicable only for one time in a subscription.

Applying discounts to an existing subscription

We have already discussed what are coupons and promotion codes in detail. Now, we will see how we can apply coupons to an existing subscription.

Applying coupons

Let's say, Oliver has subscribed to the Monthly Standard Plan without discount on January 1, 2021, and he was billed $19 immediately. He has also paid recurring charges of the amount $19 for February, March, and April. Our application FityfyMe has got first 1000 subscribers, and we have decided to give them a 10% discount on the subscription for the upcoming 2 months.

First, we will need to create a coupon Flat 10%. We will follow the same steps mentioned in the create coupons section to create it.

Coupon flat 10%

After creating the coupon, navigate to the subscriptions page and click on the `Update subscription button on which we want to apply the coupon.

Subscriptions

After the subscription page is rendered successfully, click on Add Coupon button and select Flat 10% coupon from the dropdown.

Add coupon to a subscription

Once the coupon is applied successfully, we will see future invoice amount is reduced to $17.10 and then click on the update subscription button.

Applying promotion codes

Instead of applying Flat 10% coupon directly on Oliver's subscription, we will send him a promotion code FLAT10PROMO, so that he can apply it to his subscription.

We will follow the steps mentioned in the promotion codes section to create it.

FLAT10PROMO

We can apply promotion code on an existing subscription via subscription update API only.

Let's see how Oliver can apply promotion code to his existing subscription via our application.

First, we will need to get the Stripe API Key, Subscription ID and Promotion Code.

To get Stripe API key sk_test_51IUPamDdkrcdQOlhs2b...VV2OQeFjRe1004Oahe9N3 follow steps mentioned in the Setting up Stripe account section.

To get Subscription ID, navigate to subscriptions page, click on the desired subscription and copy subscription ID.

Subscription ID

To get Promotion Code, navigate to coupons page, click on the desired coupon and copy promotion code API ID

Promotion Code

Now, let's see the subscription update API request we are sending to apply promotion code via our application.

1$ curl https://api.stripe.com/v1/subscriptions/sub_JJnCr4PJF6cZCb \
2> -u sk_test_51IUPamDdkrcdQOlhs2b...VV2OQeFjRe1004Oahe9N3: \
3> -X PUT
4> -d "promotion_code"="promo_1IhAIAHjDjtSi1tHPmjvLNxY"

Applying discounts to a customer

Instead of applying coupon to a subscription, we can apply it to a customer also.

Let's say, we have an existing customer Oliver. We have analyzed that he is a valuable customer, and we have decided to give him a $5 discount on his purchases. We will create a coupon Flat 5 in Stripe and will apply it to a customer.

Now, we will create a coupon in Stripe with 5% discount and duration forever.

Create a Flat 5 coupon

Now, let's see how we can apply a coupon to a customer via Dashboard.

Navigate to customers page and click on the customer on which we want to apply the coupon. After the customer page is rendered successfully, click on the Actions button and then click on the Apply coupon button.

Apply coupon to customer

Select the Flat 5 coupon and then the coupon will be applied to a customer successfully.

Now, let's create a new subscription for Oliver. Navigate to subscriptions page and then click on the Create Subscription button. Enter subscription details as shown below.

Create Yearly Subscription

We have selected Yearly Standard Plan worth of $190/year but the invoiced amount is $185. Now, the question is why subscription amount is reduced?

Oliver is having Flat 5 coupon so when we created a subscription for him that discount also got applied to it. If we click on the Override discount button then we will see a list of available coupons.

Applicable coupons

If we want to override the customer then we will need to select other coupons from the list of available coupons.

When, a coupon is added to a customer then it will be applied on all his future recurring charges. For this reason, Stripe recommends adding coupons to subscriptions, not customers, unless we want to discount all recurring charges for a customer, even on subscriptions added later.

Deleting discounts

We can delete coupons in Stripe via Dashboard or discount API. However, deleting a coupon does not remove the applicable discount from any existing subscription or customer. Deleting a coupon prevents it from applying to future subscriptions or customers, though.

Deleting a subscription discount

Let's say we want to delete FLAT 10% via Dashboard. This coupon is applied to Oliver's Monthly Standard Plan. Navigate to coupons page and select the coupon we want to delete. Click on Delete coupon button as shown below.

Delete subscription coupon

Let's verify whether discount is still applied to Oliver's Monthly Standard Plan or not? Navigate to subscriptions page and click on the Oliver's subscription. We will see that the subscription next invoice amount is still $17.10. Deleting coupon does not remove the applicable discount from Oliver's subscription.

Deleting a customer discount

Let's say we want to delete customer discount FLAT 5% via Dashboard. This coupon is applied to Oliver's Yearly Standard Plan worth $190 and that's why Oliver has paid $185.

Navigate to coupons page and select the customer coupon we want to delete. Click on Delete coupon button as shown below.

Delete customer coupon

Let's verify whether discount is still applied to Oliver's Yearly Standard Plan or not? Navigate to subscriptions page and click on the Oliver's subscription. We will see that the subscription next invoice amount is still $185. Deleting coupon does not remove the applicable discount from Oliver's subscription.

Yearly standard subscription

⌘K
    to navigateEnterto select Escto close
    Previous
    Next