Previewing Subscription Upgrades

This question comes up a lot on the Stripe API discussion mailing list:

"Is there a way to see what Stripe will calculate the pro-rated amount to be prior to creating the invoice?"

Let's say you have a Stripe customer who wants to upgrade from a $5 monthly plan to a $25 monthly plan. Great! All you have to do is update their subscription's plan with the new plan id:

customer = Stripe::Customer.retrieve(customer_id)
sub = customer.subscriptions.retrieve(subscription_id)

sub.plan = 'monthly_25'

On their next billing period, the customer will see a new $25 charge as well as a proration of the last month's charge, which shows up as an invoice item. Determining what that amount would be on invoice item yourself is tricky and involves some guess work. You had to calculate a formula like this:

p = fraction of time left on current subscription
credit = p * current_subscription_price
debit = p * new_subscription_price
proration_amount = debit - credit

The guess work comes in around what value p should have, since Stripe calculates down to the second.

Previewing Updates

A few weeks ago the good folks at Stripe added a way to get Stripe to do the calculation for you, so you don't have to resort to calculating it yourself. For existing customers you can preview the next invoice that they'll get. This isn't new functionality, but what is new is that you can add a bunch of parameters to influence what the invoice would look like with those changes. Here's what that would look like for the customer above:

upcoming = Stripe::Invoice.upcoming(
    customer: customer_id, 
    subscription: subscription_id,
    subscription_plan: 'monthly_25'

puts upcoming.subtotal # => 2500 + the proration amount
puts upcoming.lines.first.amount # => 2500
puts upcoming.lines.last.amount # => proration amount

Using this you can display to the customer exactly what their next invoice will look like before they upgrade or downgrade.

Mastering Modern Payments

Build a Better Payment System

Get a free five part email course all about Stripe and Rails, including the first three chapters of Mastering Modern Payments.

No spam. Unsubscribe at any time.
Pete Keen Portrait Pete Keen has been professional software developer for a decade, building payment systems and other software for companies large and small. He blogs here and at