trueinviso

[unkempt cloak]

That is a good use case for Subscription Schedules, they are the only approach for setting up changes for a subscription that will occur in the future. Updating a Subscription directly will make the changes immediately.

[solid laurel]

Is it something like this?

Stripe::SubscriptionSchedule.create({
  from_subscription: "sub_id",
  start_date: "end_of_billing_cycle",
  items: [
    {
      price: price_id,
    }
  ]
})

[unkempt cloak]

Since you're creating a Subscription Schedule from a Subscription, it will be a two step process.

First you'll create a Subscription Schedule from the Subscription. That is what is being done in the code that you shared, but since you want the Schedule to inherit everything from the Subscription initially you'll want omit the start_date and items parameters. (Those parameters also don't go directly on the Subscription Schedule object, but rather are nested inside of phases)
https://stripe.com/docs/api/subscription_schedules/object#subscription_schedule_object-phases

Once you have the Subscription Schedule, you'll want to update it by adding a new phase to it. The current phase is the phase that the Subscription is currently in, and when updating the Subscription Schedule you'll want to pass that information in so the current phase is preserved, and at the same time you'll pass in the details for the next phase that you want to create. It's in this new phase that you'll want to change the product/price that is being used.

You can see an example of creating a new phase in the third code snippet in this section:
https://stripe.com/docs/billing/subscriptions/subscription-schedules#updating

[solid laurel]

So I assume it automatically removes the products from the first phase when it moves to the second phase?

Is it recommended to use this for immediate upgrades too? Right now I'm manually adding and removing products on upgrade, maybe a subscription schedule that takes place immediately is a better option?

[unkempt cloak]

Yes, when the underlying Subscription moves from one phase to the next, it will be updated so that it matches what is shown in the new phase.

No, this is not recommended for immediate upgrades. Working with Subscription Schedules is more tedious and doing so adds unnecessary complexity if you are wanting to make changes immediately.

[solid laurel]

got it, thanks

[unkempt cloak]

Happy to help!