Referral payout runner
A small system that records referrals, decides when each one becomes payable, holds the ones that look wrong without silently swallowing them, and produces a statement somebody can argue with. The hard part is not the arithmetic; it is that every decision here is about somebody else’s money. Seven posts on the same system, one diagram at a time, with a cost breakdown and an engineering reference at the end.
- 01
A referral payout runner on AWS for a few dollars a month
The whole system on one page — record, qualify, pay — and the stamped rule version that keeps a rule change from rewriting what people were promised.
- 02
How a referral gets recorded
When a referral is created, why the rule version is stamped at that moment, how long a referral stays live, and how competing claims are resolved.
- 03
When a referral becomes payable
Why payability waits for the refund window, what a qualifying condition should and should not be, how a payout run works, and how clawback is handled without surprising anybody.
- 04
How fraud is handled without punishing everyone
Which fraud patterns are worth detecting, why the false-positive cost dominates, how a hold is communicated, and the aggressive rules that look prudent and are not.
- 05
How a disputed payout gets resolved
Why a good statement prevents most disputes, the three kinds that still arrive, how the event log resolves them, and what to do when the system was wrong.
- 06
What the referral payout runner costs
About $2 a month. One Bedrock read per referral is the only line that grows; the queue, the table, the mail and the storage are rounding errors. Plus the three ways the bill could surprise you.
- 07
Engineering reference: the referral payout runner architecture
Same system, drawn purely for engineers. Service names, region, Lambda inventory, IAM scopes, the schemas and the exact model id.
Frequently asked questions
- What is a referral payout runner?
- A small serverless system that tracks referrals, decides when each becomes payable under the rules in force at the time, holds suspicious ones for review, and pays the rest on a stated schedule with an itemised statement.
- When does a referral become payable?
- Not at signup. After the referred customer’s refund window closes and any qualifying condition is met, because paying earlier means clawing money back, which is worse.
- What happens if the rules change?
- Referrals are paid under the rules published when they were made. The rule version is stamped on every referral and the system can never apply a newer rule retroactively.
- How does it handle suspected fraud?
- It holds, tells the person it is holding and why, and gives them a way to respond. Silent withholding is what kills referral programmes.
- What does it cost to run?
- A couple of dollars a month. See part six.