Ask HN: Why is Stripe API documentation lacking so badly?

I really enjoy working with all parts of Stripe, except for reading their API documentation because it is lacking so much.

You could file a bug report with Stripe letting them know where you think they could improve their docs.

That’s something I haven’t heard before. I’m sitting here thinking Stripe pioneered good, in-depth API documentation. What exactly do you feel is lacking? I’ve been using Stripe for years and haven’t had any issues with their docs.

Easy snags when learning Stripe's API:

1. Internalizing core objects, like the Customer, Card, Tokens, and Source. And Plans / Subscriptions. Card/Source can feel ambiguous, since the API lookups are similar.

2. Order for creating / pulling up some objects. Customer's can attach a source upon creation, but can also attach it later. But you can't just look up all cards - you retrieve a card by looking up the customer first.

This helps later on if your user wants to update their billing info. Think about it: You pull up the customer first. Then a customer has cards they can delete, update, or add.

Plans must be created before subscriptions. That's another huge favor. Because on your front end, you can have the user switch between plans and have a consistent selection site-wide. Rather than just declaring an arbitrary price.

3. Understanding the difference between stripe.createSource (a reusable billing object) and stripe.createToken (a temporary billing object) [1]

4. Getting effective coverage in billing systems. Requires a ton of mocks. In order to simulate the responses to create the mocks, you have to play with the test API to get the desired outputs. The docs don't give you that.

In fact, stripe-mock [2] doesn't give you all the possible scenarios. So there's going to be a lot of time spent "bullet proofing" a subscription system. Especially if it's self-service.

I'd estimate it took about 1.5 months to get it fully working when I did it at a startup. The second time around, it's taking more time since I want to be able reusable enough to use on other websites / clients. Maybe 2-2.5 months.

[1] https://stripe.com/docs/sources/cards#create-source [2] https://github.com/stripe/stripe-mock

>it is lacking so much.

Stripe API documentation is the best i've ever seen, I really don't see what could be improved

Do you have any exemples in mind ?