Ask HN: Why is Stripe API documentation lacking so badly? | Hacker News Reader

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

11 pointsjohanlaidlaw11 comments

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

View on HN

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

Are you looking at their docs[1] or their API docs[2]? While both are helpful, they solve slightly different needs.

[1] https://stripe.com/docs

[2] https://stripe.com/docs/api

I've found their API docs to be extremely helpful in the past. What do you find to be lacking?

The team are very responsive, so as zapperdapper mentioned, I'm sure they'd welcome a bug report with details of what you're having trouble with.

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.

I'm glad to hear no one else has this problem. Must be isolated to my computer then. The docs are written really well and it is super clear how to use it. It is just my computer that hangs everytime I visit that page

I hold the position that Stripe has truly great documentation and should be held up as a standard for other people writing documentation to work towards.

I haven't found it to be lacking for any of my use cases.

Have you ever tried to use PayPal's documentation? Might make you feel better about Stripe :)

>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 ?

I wasn't clear - I really like the documentation, but my browser lacks (a lot) every time I visit the docs page. But must be my computer, since no one else has this problem

The word you're looking for is probably “lag”, not “lack”.

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

Reply on news.ycombinator.com