mav

[lyric glen]

1. It only fires once. Your use case is a bit unusual in the sense that you want different upgrade timing for upgrade and downgrade. I think you would need to control the upgrade call via your own UI (instead of let it triggers from Billing Portal), verify if it's upgrade or downgrade, then only trigger Update Subscription API in case of upgrade and delay the updating in case of downgrade
2. Same as above, I am afraid with Billing Portal you can't control the timing (the customer triggers it) and you can't branch out in your 2 cases

[hot hemlock]

Ok, thank you for your response.

So then to clarify the expected Billing Portal behavior, if I have two annual plans, Pro and Premium, and a user downgrades from Premium to Pro in the middle of the current period, the subscription will switch immediately over to Pro Annual plan and be prorated? (assuming I have proration switched on and immediate billing). Or will the Pro annual plan only start after the current_period_end date?

[lyric glen]

Yes

You can think Billing Portal is a convenience wrapper we created, instead of you manually implement an UI and call Update Subscription API. In the Update Subscription API surface, you only have the option of "proration or not" and "reset the billing cycle or not" for both upgrading and downgrading

1. https://stripe.com/docs/api/subscriptions/update#update_subscription-proration_behavior
2. https://stripe.com/docs/api/subscriptions/update#update_subscription-billing_cycle_anchor

In another words we don't have the granular setting of "do X if upgrading and do Y if downgrading" and you would want to control that logic before calling the API