As far as I can tell there is no information included in the API that states if a patron has been successfully charged or not, however, we can deduce they have been charged if the following conditions are true:
If campaign is_charged_immediately and declined_since is null
If patron created_at was in the previous month, and 72 hours have passed since the start of the current month and declined_since is null
If total_historical_amount_cents is greater than 0
Am I correct in this understanding? Are there any other conditions we can use to determine if they have been charged, or are there edge-cases where the above conditions are not viable for determining whether the patron has been charged yet.
In this case if a Patron has been charged within those 72 hours, I think, they would not show up has being charged until after the 72 hours have elapsed.
You can also check to make sure that total_historical_amount_cents for a value greater than 0, as that would indicate whether or not a patron has ever been charged at all.
That’s great, so we’re confident that total_historical_amount_cents [1] can only contain a value greater than 0 if the patron has been successfully charged?
Only the FIRST time they are charged, as I understand it. So if they were previously a patron, charged, and then they deleted their pledge, and then several months later re-pledged, the value would still be greater than 0.
Not ideal, but it does help narrow it down a little bit more.
Reviewing the documentation it looks that the only place the total_historical_amount_cents value is included is in the Pledge resource as part of a request for all pledges on a campaign, it’s not possible to obtain the total_historical_amount_cents for an individual pledge through the API, nor is it included in the webhook for a pledge. Am I correct in that understanding?
Another edge case: if you refund the user, the total_historical_amount_cents will be 0. So you’ll need to store the successful charge before any refunds.
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).
In a Charge Upfront situation, How soon after a user makes their pledge is total_historical_amount_cents updated? I ask because recently I’ve had several users who have messaged me about not having access immediately after pledging. By the time I see the message, they then have access. I’m wondering if there is a small delay that is causing this?
@LordHarvie I would expect total_historical_amount_cents to update as soon as the charge with our payment provider is done. The change to the underlying table that populates total_historical_amount_cents happens in the same database transaction as the one that grants access, so those should never be out of sync with each other.
In terms of delay after pledging, there shouldn’t be much of one. We do have to call out, like I mentioned, to an external service, but in the vast majority of situations that should complete within 1 second. If the patron navigates away from the checkout page before the request is complete (rather than waiting for redirect), it’s possible that they’d experience not having access for a moment, but that moment should be very short lived.
edit: sorry this wasn’t a proper reply! still learning Discourse
I have read carefully trough this thread and there is still something that I find confusing.
Let’s say it’s the 1-3th day of the month (PT) and my patron gets charged sometime within this timespan.
Which values do actually change from shortly before to shortly after a Patron was successfully charged besides total_historical_amount_cents ?
@alts, thanks for your reply, I look forward to the enhancements to your API!
Can you please explain what happens when a patron changes the level of their pledge, is a new pledge record created with a different id / amount / created_at? Or is their original pledge updated with new values?
PS How I wish you guys provided a demo account with some sample data to play with!
