Clawing back affiliate commissions when a customer refunds: design the ledger first

Source: Dev.to

You pay an affiliate 30% for referring a customer. Three weeks later that customer refunds. Now the affiliate is holding a commission on a sale that no longer exists, and you have to decide what happens to that money. If you only thought about this after it happened, you have already lost the clean version of the fix. I build affiliate software on Stripe, and the clawback case is the one teams skip until it bites. Here is how to design for it before it does. The first mistake is treating a commission as money the moment the sale clears. It isn’t. A commission is a claim against a sale that might still reverse. Stripe makes that gap concrete: a customer can refund whenever they want, and a card dispute can land up to 120 days after the charge. Your payout schedule (say, monthly) runs on a completely different clock. So you have two timelines that don’t line up: how long a sale can still reverse, and how soon you pay out. Pay before the first window closes and you are paying real money on revenue you may have to give back. The fix is a holdback period. A commission lands in a “pending” state when the sale clears, and it only becomes “available” for payout after N days with no refund or dispute. Set N from your own refund data, not a guess. If most refunds happen in the first 30 days, a 30 to 45 day hold covers the bulk of them without making affiliates wait forever. This one decision removes most clawbacks entirely, because the commission never reaches an affiliate’s wallet until the risky window has passed. Here is the part that saves you later: never store an affiliate’s earnings as a single number you edit. Store immutable ledger entries and compute the balance from them. commission_entries id affiliate_id charge_id — the Stripe charge this relates to type — earned | reversed | paid_out amount_cents — signed: + for earned, - for reversed/paid status — pending | available created_at

A refund does not edit the original row. It writes a new reversed entry that points at the same charge. The affiliate’s balance is just SUM(amount_cents) over their entries. You get an audit trail for free, every reversal is explainable, and you never lose the history of why a number changed. When an affiliate emails asking why their balance dropped, you can show them the exact charge and the exact reversal. Sometimes a refund or a dispute arrives after the commission went out the door, usually because a chargeback showed up 60 days later. Now the affiliate’s balance goes negative. You have three honest options: Carry the negative forward against future earnings. This is the common one and the fairest: the next commissions they earn pay down the deficit before anything becomes payable again. Reverse the transfer. If you pay through Stripe Connect, you can reverse a past transfer, but it is aggressive and it will surprise people. Reserve it for fraud or for affiliates who have gone silent with a large negative. Write it off below a threshold. Chasing back a 4 dollar commission costs more in goodwill than it returns. Pick a floor and absorb anything under it. Whatever you choose, decide it once and apply it the same way every time. Inconsistent clawbacks are how you lose good affiliates. Two webhooks drive this: charge.refunded and charge.dispute.created. Each one looks up the commission entries tied to that charge and writes a reversed entry for the matching amount. For a partial refund, reverse the same proportion of the commission, not the whole thing. A detail worth stating: process these as triggers to re-read state, not as the final word. A refund webhook can arrive while the original commission is still settling on your side. Look up the current state of the charge and the existing entries, then write the reversal against what you actually find. (Idempotency matters here too: key the reversal on the refund ID so a redelivered webhook doesn’t reverse twice.) This is a product decision as much as an accounting one. Affiliates hate surprise clawbacks more than they like fast payouts. If your dashboard shows one big “earnings” number that quietly drops when a refund lands, every reversal feels like you took their money. Show pending and available as two separate numbers, with the date each pending commission becomes available. Then nobody counts money that isn’t theirs yet, and a reversal during the pending window is a non-event instead of a support ticket. We keep payout fees at zero and we run this exact pending-then-available model, because the trust cost of getting it wrong is higher than any fee. (Disclosure: I work on Referralful, https://referralful.com/?utm_source=dev.to&utm_medium=content&utm_campaign=article , affiliate software built on Stripe.) Design the ledger and the holdback before you write your first commission. Retrofitting an immutable ledger onto a system that stored a single balance is a migration you do not want to run while affiliates are watching their numbers.