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:

Easy enough, right?

WRONG.

When actually doing this we were getting the following 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'

Links:

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

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