
Ask HN: Why is Stripe API documentation lacking so badly? - johanlaidlaw
I really enjoy working with all parts of Stripe, except for reading their API documentation because it is lacking so much.
======
git-pull
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](https://stripe.com/docs/sources/cards#create-source) [2]
[https://github.com/stripe/stripe-mock](https://github.com/stripe/stripe-mock)

------
dmlittle
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](https://stripe.com/docs)

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

------
ruairidhwm
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.

------
ezekg
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.

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

------
mod
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.

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

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

~~~
johanlaidlaw
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

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

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

