Here at Lingohub we use Stripe for handling all our customer payments. Stripe provides an amazing REST API which is well documented and generally very easy to use. However, modelling a proper payment workflow which covers all possible edge cases can be a little tricky. In this post I want to describe how we use Stripe to handle customer subscription changes in conjunction with VAT (value added tax) handling.
In general Stripe does a great job at managing subscriptions. You simply create a customer and assign an according subscription plan which has to be defined up front. The main properties of a subscription plan on Stripe are as follows:
- subscription plan name
- amount to charge
- payment interval (e.g. monthly vs. yearly)
It is important to note that the currency is in fact a customer property. So once a customer has been created and a currency has been set it cannot be changed anymore and only plans of which currency matches the customer account can be assigned. When creating a subscription for a customer an according plan is assigned and the following additional subscription properties can be defined:
- an optional trial period which determines when the first payment will be made
- an optional tax rate which is applied to all invoices created for that subscription
Handling subscription changes with Stripe
Once an initial subscription has been created the customer will be billed by Stripe automatically at the predefined intervals. Once a payment is done Stripe will also deliver a web hook notification which we use to generate an according invoice. So far things are pretty straight forward but it starts to get interesting when you consider what happens if the subscription changes:
- The subscription may be terminated at any time
- The customer may want to upgrade to a new plan
- The customer may want to downgrade to a cheaper plan
- The customer may want to switch to a different payment interval (e.g. from monthly to yearly)
- The VAT rate for the customer may change for various reasons
When modelling these scenarios it is important to understand
- how Stripe handles such changes
- how you want to handle these changes
How does Stripe handle subscriptions per default?
Per default Stripe invoices customers only at the beginning of each predefined billing cycle. This means that all relevant changes in between are collected and will be considered at the beginning of the next billing cycle. This also includes any charges that are created in between (in our case e.g. if a customer orders translations at Lingohub) which has some important implications:
- Payments are not attempted until the billing cycle ends. For example, if a customer upgrades to a bigger plan at the beginning of a cycle you will have to wait for the payment being made, potentially for a long time, e.g. in case of a yearly plan.
- You can only define a single tax rate which is applied to all items on an invoice. If you sell goods that require a different tax rate it is not possible to include all items on a single invoice.
- In case the billing frequency itself is changed an invoice is created right away as a new billing cycle is started.
Additionally whenever a subscription plan is updated Stripe prorates such changes. That means they consider the exact time that was spent on each plan and calculate a credit for the remaining time which is considered when calculating the actual amount that needs to be paid for the new subscription.
As you can see the default behaviour may be problematic, depending on your use case. This is the reason why Stripe allows you to create invoices at any point in time with the possibility to configure which items to include and if a proration should be performed.
With the basics explained, how do we handle the changes mentioned above?
1. Subscription cancellation
According to our terms of service we do not do refunds in case a customer decides to cancel his subscription with Lingohub. Since payments are usually made up front in such a case we simply cancel the subscription immediately. This also means that in this case a final invoice for all pending charges would have to be created. This cannot happen to us since we always create invoices immediately for outstanding payments (see other cases below).
2. Upgrading to a bigger plan
Whenever a customer upgrades to a bigger plan we manually trigger an invoice creation for his subscription for various reasons:
- We do not want to wait for the payment to be made at the end of the current cycle. (assume the change is done at the beginning of a yearly cycle then we would have to wait for the payment to be made for one year)
- we only want to include charges related to the subscription change, other items that may be added during the billing cycle might require a different tax rate which would not be possible otherwise
- if the customer cancels the subscription before the billing cycle ends we would have to create a final invoice which would potentially delay the cancellation process since we would have to wait for the payment before we can delete his account
For this to work properly you have to make sure that the subscription ID is provided when creating the invoice, otherwise all pending items are added to the invoice and the tax rate defined on the subscription would otherwise not be considered (you can however always set a tax rate manually when requesting an invoice to be created which overrides the tax rate specified for the subscription)
3. Downgrading to a smaller plan
Of course it is also possible to downgrade to a smaller plan at any point in time. This change is generally handled in the same way as an upgrade. It's important to note that in this case the customer may receive a credit since he already paid for a bigger plan up front and there may be time remaining on that bigger plan. In this case an according balance is added to the customer account on Stripe which is automatically considered when generating future invoices. Since according to our terms we do not refund any payments the customer has no right to get that money back. It's only fair to consider his balance for future transactions especially if you consider that a downgrade may have been performed unintentionally.
In case the subscription is cancelled this credit is lost which is also a fair thing to do since the customer stopped to use our service.
4. Changing the payment period
In case a plan change involves switching to a different billing cycle Stripe always creates an invoice immediately since the old cycle is terminated and a new one is started. In such a case we also enable proration to ensure that the remaining time from the old billing cycle is considered when making the change.
5. Changing the tax rate for a subscription
The VAT rate that needs to be applied to subscriptions depends on the country where the customer lives or where his company is registered. Therefore when the country in the billing address changes or a valid VAT registration number is added or removed the applicable tax rate for his subscription might have to be updated. This is easy as you simply have to update the tax rate on the existing subscription and the new rate will be applied to all future invoices.
In this short article we tried to point out a few things that need to be considered when integrating with Stripe for handling your customer subscriptions. Generally it is a good idea to trigger invoice creation manually, since it gives you more flexibility when it comes to ensuring that payments are done for the correct items at the right time with the proper tax rate applied. Another important thing to consider is how you want to handle prorations which is something that is determined by your terms of service.