Cancelling a stripe subscription on 'period end'

Stripe's documentation on cancelling a subscription at the end of a period isn't entirely up to date.

https://stripe.com/docs/billing/subscriptions/cancel

For cancelling at end of period, the docs say to do the following:

Stripe::Subscription.update( 'sub_', { cancel_at_period_end: true, } ) 

Easy enough, right?

WRONG.

When actually doing this we were getting the following error:

{ "error": { "message": "The subscription is managed by the subscription schedule `sub_sched_`, and updating any cancelation behavior directly is not allowed. Please update the schedule instead.", "type": "invalid_request_error" } } 

After contacting stripe support, if you wish to cancel at the period end you need to do the following:

1. Update phases on subscription schedule object to pass only current phase.
2. Set end_behavior to 'cancel'

Stripe::SubscriptionSchedule.update( 'sub_sched_', {end_behavior: 'cancel'}, ) 

Links:

https://stripe.com/docs/billing/subscriptions/subscription-schedules#updating

https://stripe.com/docs/api/subscription_schedules/update?lang=ruby