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' sub.save
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.
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.
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.