#neha_best-practices
smoky marshBOT
đź‘‹ 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/1215138873537994802
đź“ť Have more to share? Add more details, code, screenshots, videos, etc. below.
stone summit
I got cut off. Does that mean that I can no longer use the customer portal at all? Instead, do I need to figure out the customers current and future subscription, and direct them to the checkout session with the right subscription schedule? I think I’m just confused about where in the webhook lifecycle the subscription schedule gets updated.
sharp tuskBOT
near narwhal
Customer portal doesn't support upgrading or downgrading a subscription in the future, i.e. at the end of the cycle. This can only be done via direct API integration using Subscription Schedule: https://docs.stripe.com/billing/subscriptions/subscription-schedules/use-cases#changing-subscriptions
stone summit
Right but I still don’t understand the flow. So the user is on sub A. They change to sub B. Do I direct them to a checkout session with this schedule change baked in?
And then I listen to the “update” hook as confirmation that the change has been processed? Will the update hook even be called if it’s a delayed change?
near narwhal
Let's step back a bit. With subscription schedule, there won't be a new subscription created. Subscription schedule will update the existing subscription only when the time specified reaches, e.g. end of billing cycle. Checkout Session is not required.
When the subscription is updated at the end of billing cyle, customer.subscription.updated event will be sent
stone summit
So with the customer portal, it would clearly say to the user that they’re going to be charged X today and Y going forward
If I just change the schedule how will the user understand the financial ramifications?
near narwhal
That's incorrect. Customer Portal and Subscription Schedule are two different integrations.
Customer Portal doesn't support Subscription Schedule and it doesn't support downgrading the price in the future. If the customer downgrades the price in the Customer Portal, it will be an immediate change.
To downgrade a price at the billing cycle ends, it can only be done via direct Subscription Schedule API: https://docs.stripe.com/billing/subscriptions/subscription-schedules/use-cases#changing-subscriptions - Customer Portal or Checkout Session will not be involved
stone summit
Okay so… somewhere in my UI I let the user click a new plan. If this plan is an “upgrade” I want the behavior to be pro-rate and start immediately. Does that require a checkout session?
If the plan is a downgrade, I hit the subscription api and make the new schedule, and show an alert to the user saying “it’s been updated and will go into effect next month”’. The next month I’ll receive the updated webhook and process it real time.
Does that sound right?
And also, maybe the user can see their scheduled changes via the customer portal?
heady crane
hello
stone summit
Hi
heady crane
Excuse me, why can't I send messages
near narwhal
@heady crane This channel is for @stone summit. Please use #help for your questions. We will create a thread for you from there
If this plan is an “upgrade” I want the behavior to be pro-rate and start immediately. Does that require a checkout session?
Checkout Session is not required. Checkout Session is for Subscription creation and it doesn't support any update.
If the plan is a downgrade, I hit the subscription api and make the new schedule, and show an alert to the user saying “it’s been updated and will go into effect next month”’. The next month I’ll receive the updated webhook and process it real time.
You will hit the Subscription Schedule API to schedule the existing subscription for future changes
maybe the user can see their scheduled changes via the customer portal?
Yes! Customer will see the scheduled changes in Customer Portal, but he/she won't be able to update it
stone summit
So how do I do the upgrade & pro-rate in a way that the user understands what they’ll pay today?
For example the user upgrades from a $40 plan to a $60 plan mid month. They are charged $10 immediately. How do I show them that so that they can confirm the charge?
Is there anything I can do to improve transparency?
runic pewter
It's for you to display the changes to them, isn't it. Eventually when you use Subscription Schedule API, you will handle the process yourself, not in Customer Portal
stone summit
So you’re saying I have to explain to them that it will be pro rated (even if I can’t say the exact dollar value) and that’s the best I can do
If that’s the case then a point of feedback would be to add an endpoint to the schedule API that let’s you “validate” or “simulate” a change so that you can get the line item information and display it to the user
Then once the user confirms you can call the real endpoint and make the change official
runic pewter
There is the Upcoming Invoice API for that purpose!
It can simulate a change if you passing in the hypothetical parameters
stone summit
So I would pass the new subscription schedule and it would tell me the price?
You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass a proration_date parameter when doing the actual subscription update. The value passed in should be the same as the subscription_proration_date returned on the upcoming invoice resource. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_proration_date on the upcoming invoice resource.
runic pewter
Yes, but curious where did you take these text from?
stone summit
The docs
runic pewter
specifically?
stone summit
stone summit
I think I have two last questions. I have a credit based system, and the user can buy more credits if they need. For that, I need the checkout session, right?
runic pewter
For generating new transaction, yes
stone summit
similarly, the “free trial” is a fixed grant of credits. If the user finishes his credits and wants to void the free trial in order to start their first month, is this also something I do with the subscription schedule API?
It should cancel their remaining free days and immediately invoice them for the first day of a new cycle
runic pewter
Yeah I think that's possible too. Need to try the API in Test mode to see
stone summit
What would you have said instead?
runic pewter
No I miss-entered before finish typing
stone summit
Ok so it would be again modifying the schedule to remove the free trial portion
Got it
runic pewter
Yes
stone summit
Thanks for your help