Nooooooooo.

I dislike Stripe's API. There are parts of it that just make no sense.

Say, you want to set a billing date for that fancy subscription. Yeah, just set a trial date until the billing date you want. Oh, and don't forget to charge a prorated difference (by hand, with charges)!

Want to upgrade that subscription? Yeah, cancel that subscription and start a new one. Oh, and don't forget to set that trial again!

Want to cancel that subscription but not until their next billing date? Hahaha, yeah no. You need to cancel now through Stripe and set up a process to cancel on your side. (Not the biggest complaint, but really. If I am having Stripe manage my subscriptions, they should do it all)

And I am sure there are many other details which would also drive me mad.

With all of that said, I think Stripe's API is definitely one of the better ones since my complaints are more functionality / feature requests than complaints about how it is set up.

(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 eduardo@stripe.com.

No way!

Thank you so much for the response! Complaining on the internet finally worked! :) I definitely hold nothing against Stripe, I still love you guys.

Thanks Eduardo. I've interacted with you (I think) a couple times and really appreciate the effort you all put into customer outreach. It is appreciated. I will have my team jot down thoughts on subscription functionality and send it over.

Is this in an obvious place in the docs or in an FAQ?

- https://stripe.com/docs/api#subscriptions

- https://stripe.com/docs/subscriptions/guide

Stripe is quite good

I agree. Their subscription functionality is half-baked. We're 2 years into using Stripe for subscription management and it's such a hassle to move anywhere else that we keep hobbling along with it.

My advice when starting a SaaS company: think through your subscription software early on, before it's a headache to even think about migrating away.

Also, the provided Java client is garbage (you need to put all the arguments into an untyped hashmap that corresponds to the JSON, WTF?).

And why are there separate clients for Java and Android, which both use the same namespace differently?

And why do I need to set the API key as a global for the general Java client, while the Android client (sensibly) lets me give it as a constructor argument?

I opted to just roll my own subscription system and use normal charges periodically as needed.

I recently used Laravel Spark [ https://spark.laravel.com/ ] to manage all the subscriptions and I really love it! Before I had to do it all by myself and it was a nightmare and so much time taken away to develop the real app. I highly recomment it for any SaaS product. It gives you a huge jumpstart and you can concentrate on developing just your app. Btw, it supports both Stripe and Braintree.

I did that too, mostly because I am splitting transactions to connected accounts and subscriptions don't play nicely with that functionality, according to the docs.

So you want to set a billing date and then charge a pro-rated amount that first month?

And what do you mean "upgrade"? You can move from one plan to the next and charges are pro-rated automatically for you.

I, too, loath the amount of time we've spent on subscription/billing but I'm just surprised that none of the issues you've listed are really causing any pain for us.

Sadly, Stripe API is not so great :(

It seems like the API is way too complex to do certain operations. Especially some very common use cases: for example, how to apply discount for next year for customers who already have subscription (we wanted to emulate how Comcast always gives you discount if you want cancel and took us weeks to make that working ...). I think they do want to fix all these issues but API is not designed to be easily expandable.

It's actually very hard to find a decent REST API :(

My points here are the following:

1. Think very very hard about how people will use your API <-- this is critical. This also includes operational characteristics of your API (performances, how often it is going to be called, optimization, etc.)

2. Make API easily expendable. Especially relationships between models. Sometimes, it is ok (or even better) just to organize it as "SQL wrapper". Like SOQL by Salesforce - but that again depends on number 1.

^ Came in to say this. I use Stripe for inspiration on their API, docs, and even the general UI/UX to get a feel for something simple yet elegant.

Jeez, glad I'm not the only who feels Stripe's API is basically the golden standard when it comes to a properly implemented REST API and documentation.

-1 for Stripe. The API is designed without any thought how the use cases need to use it. Leaks the JSON structure of the document to the client. This breaks your code when they change the JSON structure.

I'm not sure what you mean about changing the JSON structure; the Stripe API is versioned and you have to opt-in to any updates, including breaking changes like removing or renaming keys in the response.

Well, all code depending on JSON presumably breaks when that JSON changes. That's what versioning is for.

What do you mean by "Leaks the JSON structure of the document to the client"?

Even better is the realtime support on their IRC channel.

+1 for Stripe. BlockScore is another one similar to Stripe in terms of docs and intuitive design.

I feel like their API isn't super uniform in a lot of the ways it's integrated, but I will give them a +1 for allowing very easy versioning.

nit picking devil's advocate: not all of the API is documented. There are some features that exists, but you have to know about. Granted, this is intentional. e.g.: "billing_cycle_anchor" in the subscription API.

+0.

Some parts are great, other parts not so much. My thoughts echo the other's here.