Quick intro first, Hi, my name’s Stephen, and I work on our payments team.
This is a great question, and your understanding of things is spot on. High-level, we’ve definitely decided that our roadmap for next quarter is going to solve this problem and expose a new resource that answers these questions with hopefully a lot less headache for developers. This needs to happen!
Phew.
For the record, I’m impressed by the detective work you’ve done to figure out those points, since my suggestion is just going to be a hybrid of your first and third points. Here’s our recommended best practice:
If declined_since is null and total_historical_amount_cents is greater than 0, then treat the person in question as a valid patron. That said, this doesn’t account for our pledge pausing feature (they would meet the above criteria, but not necessarily have paid in the most recent month), but that’s a pretty exceptional scenario right now.
declined_since is the date of the most recent charge attempt if it’s still in a declined state. I would only ever treat this as a boolean value (is it null, or is it not null, since while the date is useful to us internally for retry purposes, it’s not super useful outside). Total historical amount cents is exactly what it sounds like, but as @nomes mentioned, refunds do deduct from that amount. For what it’s worth, I think that if that number does go to 0 because of refunds, the person in question shouldn’t be treated as a valid patron anymore (so no need to store pre-refund values).