(I work at Stripe.)

Although it’s kind of proving your point that the API could be easier to use/better documented, here are some simpler ways to do what you’re looking for:

* Upgrading a plan (no cancellation needed): https://stripe.com/docs/api#update_subscription-plan

  > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d plan={new_plan}`

* Canceling a subscription at the end of the billing cycle (no need to handle on your end): https://stripe.com/docs/api#update_subscription-at_period_en...

  > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -X DELETE -d at_period_end=true`

* Anchoring subscription to a date (sorry! :( , this is undocumented but should be out soon): https://stripe.com/docs/api#create_subscription

  > `curl https://api.stripe.com/v1/subscriptions/sub_foo -u sk_test_bar: -d billing_cycle_anchor={timestamp}`

That said, agreed overall that our subscriptions support needs some love. We're starting to spend more time on exactly this, so would love any feedback you (or anyone else reading) are willing to share. I'm [email protected].