#morunas
zinc zealot
floral venture
Phases have an iterations property, if that is set the phase will end after that many cycles of the subscription. So a way to do that at the end of the current cycle would be to create a subscription off of your existing one and set it to have iterations: 1 https://stripe.com/docs/api/subscription_schedules/create#create_subscription_schedule-phases-iterations
Otherwise you can set the phase's end to be the cycle end with timestamps
solemn fiber
Thank you for the quick follow up, I'm going through the documentation to try to really understand how this works.
so I would do
two phases? the first with iteration 1 and the exact same price ID that is running?
and then another phase which just sets whichever new price and will automatically go on once the first one ends?
floral venture
Correct, that would achieve the behavior you described
solemn fiber
Ok cool 🙂 and then being end_behavior default release, then once that last step is applied the SubscriptionSchedule will disappear and the subscription will just run as expected
floral venture
Exactly! A schedule like that would change the subscription's price at the start of the next billing cycle and then release the underlying subscription
solemn fiber
Ok seems to be straight forward (just a bit confusing at start... I was expecting an API like "cancel_at_period_end" but for "change_at_period_end" but of course the schedules mechanic is a lot more flexible and covers a lot of cases)
One more question... what is the best way to keep track on that "pending downgrade status"? I like to keep all state (at least as much as possible) on Stripe's side as that simplifies things a lot, but in this case I don't see a connection between a Subscription object and Subscription Schedules. Would it be something like updating Subscription metadata with a schedule ID? or is there a more immediate route?
I mean I want to show our customers their subscription state (e.g. "Will downgrade to X at date") so I guess I'll need to to query that separately each time I'm handling their subscription to see if it will change, and in order to keep least state on our side, one way to link the subscription to the the schedule would be to store its schedule ID in its metadata
floral venture
Subscription objects have a schedule property that will be populated with the schedule's ID while the schedule is working with them. You should be able to check that: https://stripe.com/docs/api/subscriptions/object#subscription_object-schedule
If you aren't seeing it in your testing, send me the subscription ID and I can take a look
solemn fiber
Ah sorry my bad, was looking at the parameters when creating a subscription instead of the retrieved object. Sorry!
I think that's all 🙂 as always you guys rock at giving dev support!
Wish you a great 2023!
floral venture
Great to hear! Just let us know if you run in to anything else
Have a great 2023 yourself!
solemn fiber
Ok I do have one more question - I would like to give the user a preview of what will happen, so how does a scheduled downgrade play with previewing an upcoming invoice?
I can see upcoming invoice may receive an unstarted schedule ID, but I don't understand how I can create a not yet started subscription schedule when the first phase applies immediately to set iteration 1
or should I just use the usual upcoming invoice subscription field, and then define a future subscription_start_date and price in the items?
floral venture
Good question, checking in to whether there is a good way to preview this here and will get back to you
solemn fiber
Thank you. I already tested and subscription_start_date can only be set on creation. Will try with subscription_proration_date (sometimes trial/error helps xD)
well when I set subscription_proration_date to the current subscriptions current_period_end, then it correctly gives no proration lines and says next_payment_attempt will be at the correct date and with the correct amount. The only odd thing is in the invoice returned it says period_start and period_end are the current perido (as in period_start in the past), where I would have expected the invoice to be for the next period... so that upcoming invoice's period_start == current_period_end
solemn fiber
I think I found away, using your second suggestion of creating a schedule with start_date = currentSubscription->current_period_end, and then just one phase with the new price
That creates a not yet started schedule which I can pass the id into the upcoming invoice and the data returned seems accurate. It would still be great to know if this is the actual "right" way to do it, in case there are some caveats I'm not considering.
The downside of course is that should the user decline when previewing...then another query needs to be done to clear the schedule. It would be great if the previewing would be isolated and not change any state
Small detail... on this last solution attempt, the returned data gives period_start and period_end with the same value (the end of currentSubscription->current_period_end), which is also odd
I'll need to be away for a while (child / dinner) but I'll be back later and it would be absolutely awesome if I could get further clarifications on this point so please just reply whenever you can / know more. Really appreciate all the support 🙂
floral venture
Gotcha, nice workaround! Yeah, with our current restrictions, I think creating that future schedule and passing it in is the best way to achieve this. Looking in to why that data was odd and will get back to you
solemn fiber
Ok thanks 🙂 well both these solutions seem to work(ish) as both solutions return the expected lines and amount, but both have CONS and seemingly bugs/issues with the period_start and period_end values
a) using normal subscription based previewing with proration date set in the future - PROS no state is changed, CONS feel iffy that is does not use the feature that will execute the change (SubscriptionSchedules), and the returned period is equal to the current period instead of the the period that invoice should cover (future period)
b) using the future schedule and schedule based previewing - PROS period_start is correct, allows previewing via the same feature that will execute the change (SubscriptionSchedules) CONS state is changed and requires reset to remain consistent, returned period_end is the same period_start
floral venture
Not finding any other ways to do this or any other catches other than what you have noticed. I will say that when using subscription_proration_date, it isn't that fundamentally different than a schedule, as the schedule just does more or less do a normal subscription update at the specified time. So as long as the scheduled phase would be the same as your current subscription's configuration, the results should look the same there.
I can put in feedback to fix the period start and end behavior here, or to expand how schedules are used here, but I can't guarantee if/when that will get added. I think you have two fundamentally viable options here though at the moment you will need to write some logic to find the correct period start and end if you are displaying that info to the user in some way.