My old article on Best Practices for Using Stripe API has been super popular and you’ve been asking for more! Here are couple of tips for handling subscription upgrades with Stripe API.
When is Stripe’s own proration handling working ok? When do you need to force-send invoices to make sure you’ll get your money?
As a general rule, it’s best to try to charge customer on the same month he upgraded or on the next.
When the customer gets the bill and wonders why he was charged extra, he’ll still be able to remember upgrading. That will save us from dunning and disputes. Stripe makes prorations and upgrades easy, but there is a pitfall - annual subscriptions and per-seat pricing.
HOW DOES STRIPE PRORATE SUBSCRIPTIONS?
When subscription length changes, e.g. when upgrading from monthly to annual subscription, Stripe charges the customer immediately.
When the subscription length does not change, prorated amount is moved to customer’s next invoice. This happens with per-seat pricing too.
TIP 1: CHARGE ANNUAL SUBSCRIPTION PRORATIONS IMMEDIATELY
When customer upgrades from annual plan to another annual plan, create an extra invoice. As Stripe’s own support article on prorations explains, this will sweep up the proration invoice line item that Stripe created, but didn’t yet charge.
What’s the problem?
Ben buys a $100/year subscription. He gets charged $100 right away. He takes a look on the service again and realizes that he’s on a wrong plan and upgrades to the $200/year plan. Stripe creates an invoice item for the difference, $100, and stores if away for the next invoice. One year after, Ben gets charged $300.
Here’s how this looks in Stripe:
What this means is that Ben’s paying for the cheaper plan and using the more expensive plan - for the whole year.
When he gets the extra charge next year, he might not remember the old upgrade and may think that he got charged too much. He might have already cancelled too, and may refuse to pay or even dispute the charge.
TIP 2: CHARGE ANNUAL PER-SEAT PRORATIONS USING A THRESHOLD AMOUNT
Stripe API has a handy way to preview the upcoming invoice. When customer buys more seats, you can check how big the proration is. If the amount exceeds your threshold amount (whatever is reasonable for your business), create an invoice to charge it immediately.
Pete Keen has a nice hands-on articles on how to use the upcoming invoice API point
What’s the problem?
If customers change their seat usage rarely, there is no problem.
If customers increase and decrease seats constantly and you’ve set the system to charge prorations right away (as in Tip 1), your customers may receive 5-10 invoices each month! For an annual subscription! This can get annoying for your customers really fast, especially if their bookkeeper is charging per handled invoice (as mine is).
TIP 3: AVOID MODIFYING ACCOUNT_BALANCE TO MANIPULATE PRORATIONS
You may end up in a situation where you’d like to manipulate the upcoming proration by adding/removing some Stripe account balance for your customers. Please don’t.
You have plenty of other options. You can use discount codes. You can discontinue the old subscription before upgrading to the new. Or you can run the subscription update with a prorate:false option to prevents all prorating.
What’s the problem?
Most SaaS metrics and analytics apps that’ll automatically calculate your metrics will assume that any account balance was either:
Paid by customer at some point B. A discount given to the customer
Tweaking the account_balance may cause errors in your metrics. If you’re a customer and you’re worried about this happening to your dashboard, just email me - in most cases the data can be patched.
It can also be a real mess if you get refunds to subscriptions you’ve tweaked. Please see my Best Practices for Using Stripe API - Tip 1 explains how you can actually lose a significant amount of money in cases like that.