More Kvetching About Stripe's Documentation

I’ve been struggling with Stripe’s documentation for a while, and it just occurred to me what the issue is: it’s not clear enough on the basic concepts of its working.

For example, there’s plenty of documentation about how to use Stripe to create invoices: using the API, using the Dashboard, all good. But I need to know how Stripe arrives at the calculation of the amount_due field, and I don’t know where I can get that. The API docs is not useful. It states the starting_balance is involved, but it doesn’t go into details how, or what happens if the balance is negative. Nor does it go into details as to how the ending_balance will change based on the starting_balance or the amount_due. There’s nothing at all on what the value amount_paid is, simply saying that it’s “the amount, in the smallest currency unit, that was paid.” Would that be the total of all the successful payment intents?

What I really want are some maths or logical expressions in how the amounts relate to each other. Something like ending_balance = amount_due + starting_balance, or amount_due = grand_total + starting_balance, or amount_paid == sum(payment_intent.amount, where payment_intent.status == 'paid'). Something concrete I can tease out and go to anyone who asks, “yes, the ending balance will be adjusted based on the amount due in this manner.”

Maybe it’s assumed that everyone using Stripe at least know basic of accounting, like “due” meaning the amount of money we want the customer to give us. I mean, I think I know what that means, but I can’t really go to someone with this reasoning without linking back to Stripe and proving my work. I’m not an accountant, just some poor dev that knows how the Stripe integration works from a technical standpoint. Maybe the complexities involving in keeping balanced accounts on Stripe side precludes make this information available. That’s a fair call, but it would be nice if the documentation says that. At least that’s better than making assumptions.