Proration Calculation

[Jonathan Parker]

I am working on a subscription management application. I have to calculate the pro-rated amount of the plan(s) when the user switches from one plan to another.

I have been able to accurately calculate the pro-rated amounts when a user switches from a lower priced plan to a higher priced plan. However, when a user downgrades their plan, the same calculations don't match the invoice created in Stripe.

for example,

User upgrades for a free plan to a $10/month plan today. The pro-rated amount is calculated to be $1.94. I then downgrade that user, about 2 hours after the upgrade, and the pro-rated amount is $1.90.

Is there a way to see what Stripe will calculate the pro-rated amount to be prior to creating the invoice? (I saw a previous thread that talked about this, but I'm guessing it hasn't been implemented yet).

If there is no "preview" available...can you tell me how the amounts are calculated? Is it to the day when upgrading and to the hour, minute, 1/2 hour when downgrading?

Exposing an accurate charge amount prior to charging our users' credit card is essential.

thanks.

[Peter]

Hi Jonathan,

Thanks for writing in! 

In terms of how prorations are calculated, we calculate the fraction of time left on the current subscription's period (call it p). We credit an amount equal to p * current_subscription_price, and debit p * new_subscription_price. From a design perspective however, we'd much prefer to just expose a preview of what this calculation will look like, instead of making you have a matching version of this logic.

The bad news is that we currently don't have any way of doing this. The good news is that we are actively working on implementing this, and will have something out really shortly. Coming soon to an api-announce near you!

- Peter

[Peter]

To close the loop on this, this was just shipped! I did a little bit of explaining of this feature in another thread [0], but I'll paste it here for convenience.

-Peter   

[0] https://groups.google.com/a/lists.stripe.com/d/msg/api-discuss/VtK96YIWYTM/fuyB-ICShaIJ

COPIED

We actually just shipped this feature today! I just missed the cutoff for the weekly API announce update, but it'll make it into the email next week.

The upcoming invoice API now allows passing in a subscription_plan parameter, which will simulate updating that subscription to use the provided plan [0]. The response will be what the next invoice for that subscription would look like, if that update was actually done. This invoice will include the line items for prorations done as part of the plan change, if any. You can use this invoice to preview to a customer what the change would cost them.

Upcoming invoices now have an extra field `subscription_proration_date` which records the time for which the prorations were calculated. The recommended way of filtering the invoice preview for only the fake/preview prorations is to filter by `period[start] = subscription_proration_date`.

Since Stripe does proration down to the second, the amount of the prorations can change between the time the preview was done, and the time the actual update is applied. To avoid charging an amount inconsistent with what is previewed to the customer, you can now pass in a new parameter to the subscription update API, `proration_date`. This will perform the prorations as though they were done at the time provided by `proration_date`. By passing in the value of `subscription_proration_date` from the invoice preview as `proration_date`, you can ensure that the applied proration matches up. (We recommend only honoring previewed prices for a limited amount of time. For example, you might want to do a check that the customer pays no more than 30 minutes after they see the initial preview.)

[Jonathan Parker]

Peter,

Thanks for update. Perfect timing too, our subscription feature is just about ready to go out the door. 

I started implementing the necessary calls and have come across some issues, that I'm guessing are relatively unique to our setup.

The first problem I came across is that the proration preview only works with existing customers and subscriptions. Our implementation leverages the billing_cycle_anchor attribute to ensure that the subscriptions start on the first of the month. This implementation results in a pro-rated charge when the customer first signs up, but because the proration preview requires a customer and subscription id, I can't use for users signing up.

I worked around this issue by using our application to create a "DO NOT DELETE" customer with a subscription to our free plan that starts on the May 1. I use the customer and subscription id in the call to get the upcoming invoice. However, the invoice that is returned only has a single line item for the full amount of the plan I'm switching to instead of a single line item for the pro-rated amount from today through the end of the month.

I'm guessing these issues are related to our use of the billing_cycle_anchor. Below is the endpoint that I'm calling. Please let me know if that is something that I'm missing, this feature is very important to our implementation, so I'd love to get it implemented before go live. Thanks.

Endpoint

v1/invoices/upcoming?customer=[CUSTOMERID]&subscription=[SUBSCRIPTIONID]&subscription_plan=[PLANID]&subscription_quantity=1&subscription_prorate=True&subscription_proration_date=1428550400

[Peter]

Hi Jonathan,

That's a completely reasonable use case. The API has just been updated to allow previewing an upcoming invoice after adding a new subscription to a customer, including doing so with the billing_cycle_anchored_at parameter. (The anchor parameter is undocumented, since that feature is in general not yet publicly documented, but is considered to be fully supported.)

You should now be able to make a request along the lines of: /v1/invoices?customer=cus_0&subscription_plan=plan_0&subscription_billing_cycle_anchored_at=123456, and it will do the right thing.

- Peter

[Jonathan Parker]

Peter,

Thank you very much for getting the billing anchor support implemented, that was a huge help. I was able to get it implemented and it works perfectly. The problem I'm running in to now is that when I go to actually update the subscription I'm getting an error stating "Cannot specify proration date before the current subscription started". I'm getting this because my subscription's billing_cycle_anchor on 5/1/2015, but I'm changing my plan today.

On Mon, Apr 13, 2015 at 6:51 PM, mrfrezz98 <mrfr...@gmail.com> wrote:

How do I actually get customers what do I have to do

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at http://groups.google.com/a/lists.stripe.com/group/api-discuss/.

To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.

--

-Parker

[Jonathan Parker]

I was wrong. We were having a caching problem in the app that was causing the pro-ration date to be incorrect when updating the subscription.

Awesome feature....good work. Thanks.

--

-Parker

[Peter]

Glad to hear that it's all sorted out! Feel free to drop me a line if there are any other questions about the proration preview feature!

- Peter