#lil-nasty_best-practices
wild shardBOT
Below are links to other discussions we've had with you in the past week in case you want to review that information. If your question is related to one of these previous discussions, please provide a comprehensive summary of the current state and what you need help with now. We help many users simultaneously, so a summary allows us to resolve your issue as soon as possible.
- lil-nasty_best-practices, 6 days ago, 6 messages
limber sierraBOT
👋 Welcome to your new thread!
⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.
⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.
🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1262487844434477220
📝 Have more to share? Add more details, code, screenshots, videos, etc. below.
full gust
I see that the doc says to pass a proration date for when to apply the proration.
Is it problematic to update the subscription with a proration date that has passed?
What is the proration behavior if the user is switching from annual to monthly billing?
If the user switches from a monthly plan to an annual plan how would proration be handled in that instance?
wicked pier
Have you tried doing that in test mode? As far as I know that should work and would be the expected way to backdate a proration. Would definitely test that in test mode first though
full gust
I haven't tried yet... reading docs and want to discuss desired behavior w/ product manager before writing all the code. I assume I'll be safest to actually test (which I plan to do) but wanted to see if you guys could help out with some of the general ways this works/is handled and how to manage everything as smoothly as possible
I appreciate any insights you can offer
I assume the first question is just one I'll have to try in test mode
For the interval switching I think the update subscriptions documentation (https://docs.stripe.com/api/subscriptions/update) makes it clear that the default behavior is to sum the proration amount (negative or positive based on scenario) with the new regular payment and charge that on the next date of billing (not sure how this is selected in some instances though).
If the user switches from monthly to annual I think it would likely wait until the renewal date and simply charge the yearly amount at that point and from then on it will charge annually.
If the user switches from annual to monthly I assume the behavior is that it credits the amount remaining in the annual subscription to the customer object, and begins billing on a monthly basis and applying the credit until it runs out.
Are those correct assumptions? Or will I just need to test using test clocks and watch very closely?
wicked pier
Good questions, let me see what we have about that in our docs
Is there a specific usage-based billing doc that you got that info about interval changes from?
full gust
I've just looked at update subscriptions api docs and the prorations docs
https://docs.stripe.com/api/subscriptions/update
https://docs.stripe.com/billing/subscriptions/prorations
wicked pier
From the API reference I see
The billing interval is changed (for example, from monthly to yearly).
And from the metered billing docs I see
You can update a subscription item’s price during a billing cycle. However, we only reflect usage occurring after the update on the invoice. Usage occurring before the change won’t be invoiced.
https://docs.stripe.com/billing/subscriptions/usage-based/pricing-models#mid-cycle-updates
So my initial understanding is that you can charge immediately for the switch or not charge at all.
full gust
If a proration is crediting an account is it possible to just refund the credit and carry on with billing at the new rate? For simplicity sake?
Main case I would think we might want to do that is if we switched from annual to monthly... perhaps we refund the remainder and then just bill monthly... that way we don't have to track account credit and display it on the user's billing section
wicked pier
Oh I may have misread your question. Are you using metered billing here? Or is this a standard monthly rate and a standard annual rate?
full gust
Standard subscriptions
I see here there's 3 options, basically charge immediately, charge at next billing, don't charge proration
Not charging is simple enough
But the always_invoice option (immediate) makes sense when upgrading, but downgrading is a bit confusing bc there is credit to the user
wicked pier
Ah gotcha, so what happens when you specify create_prorations or always_invoice is that we create invoice items on the customer and those get added to whatever the next Invoice for that subscription is
And then always_invoice makes sure that that invoice is created right now.
So with create_prorations which is the one that would create the scenario that you describe. We create two invoice items to credit and debit for the time already used and the time remaining on the new plan and add them to the Customer and that will get attached to the next invoice whether it is the subscription cycling, you manually creating an invoice on the Customer, or another proration that bills immediately.
full gust
Is there anyway to avoid storing credit on the customer in a downgrade/switch from annual to monthly scenario?
wicked pier
Yes, you can specify proration_behavior='none'
So you can for example have logic in your code to use always_invoice on upgrades and none on downgrades
full gust
I see, but in the none scenario any credit they have is just lost, right?
If we wanted to refund we have to manually do that, or do it in an extra step on the api, right?
wicked pier
proration_behavior is a per-update setting. So it wouldn't effect any existing credit that they have from other prorations, setting none means that the update itself does not generate new proration invoice items
full gust
Can you leave the ticket open so I can type out a few scenarios and you confirm my understanding?
wicked pier
And that is correct, refunds are always a separate step for prorations
Also a very helpful tool here is Test clocks, they let you simulate the passage of time in test mode to see exactly how scenarios like these play out https://docs.stripe.com/billing/testing/test-clocks
and yes, happy to consult on scenarios
full gust
Yeah, test clocks are really nice! Glad to see that got added to sandbox.
full gust
Assume all changes happen at dead center of interval for simpler calculation. Prices are
**Basic ** $5/month | $50/year
**Premium ** $20/month | $200/year
Scenario 1 - Basic monthly => Premium monthly - always_invoice
User immediately gets charged $17.50 billing interval gets reset to charge a month from upgrade moment at $20/month
Scenario 2 - Basic monthly => Premium monthly - create_prorations
User gets charged $27.50 at next renewal date and will be charged $20 from now on at the original interval
Scenario 3 - Basic monthly => Basic annual - always_invoice
User immediately gets charged $47.50, 1 year later user charged $50
Scenario 4 - Basic monthly => Basic annual - create_prorations
At next monthly renewal user gets charged $50 and renewal date switches to 1 year from that day and every year after
Scenario 5 - Basic annual => Basic monthly - always_invoice
User credited $25, immediately charge for $5 and every month after charged $5 on credit until it runs out at which point they pay $5/month
Scenario 6 - Basic annual => Basic monthly - create_prorations
At yearly renewal time user charged $5 and switched to monthly payments thereafter
wicked pier
Reading through these:
In Scenario 1, I think they would get charged $7.50 ($20/2- $5/2) because switching between monthly prices does not inherently change the billing cycle. That being set you can reset the billing cycle anchor manually on the update, at which point I think your understanding of the situation is correct. https://docs.stripe.com/billing/subscriptions/billing-cycle#changing
I think Scenario 2 is correct. We would create an invoice item for -$5/2 = -$2.50 and one for $20/2 which is $10. So a net of $7.50 would get added to the next $20 invoice
I think scenario 3 is correct.
I actually think in Scenario 4 they would only pay $47.50. I think create_prorations would make an invoice item for -$2.50 and that would immediately get applied to the yearly invoice that is now betting paid.
In Scenario 5 is correct.
In Scenario 6, they would be charged immediately. To clarify, when the cycle length changes (yearly->monthly or monthly->yearly) the billing cycle will always reset and I think that means always charging immediately for any proration invoice items that were just created.
The server isn't bust at the moment so I will try to test these in test mode to see the actual results. Would reccommend that you do so as well if you are not already on it
full gust
I'll be sure to test all of these when I get the code in place, really just want to understand as deeply as possible before discussing w/ product manager and determining the desired behavior
Please let me know what you find! Thanks very much for the help
Btw is it possible to create subscriptions and test them via test clocks in sandbox mode in the stripe dashboard ui?
full gust
Ok, awesome! Thanks so much for your help
wild shardBOT
wicked pier
Confirmed what I said for all of those scenarios in my testing.