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