Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Referral payout runner series ~6 min read

A referral payout runner on AWS for a few dollars a month

Referral programmes fail in a predictable way. Somebody refers three friends, sees nothing appear for two months, asks, gets a vague answer, and tells everyone the programme does not pay. The money was usually fine; the visibility was not. This post walks through a small system built around that failure rather than around the arithmetic.

a parking garage at night with the lights on
Photo by Eiliv Aceron on Unsplash

Key takeaways

  • A referral is stamped with the rule version in force when it was made.
  • Payable means earned, not signed up. Pay after the refund window, not before.
  • A held referral is visible to the person it belongs to, with a reason.
  • Every payout comes with an itemised statement somebody can dispute.
  • Designed on AWS for about $2 a month.

The whole system on one page

Before any code, here is the shape of what we are designing.

System: referrals recorded, qualified and paidThree boxes across the top sit outside the AWS account. On the left, Referrers, who have a link and receive a statement. In the middle, Orders and refunds, from the existing systems. On the right, Payments out, on a stated day. Each connects by an arrow to the AWS account container below. Referrals flow down into the account. What happened feeds in. Payments and statements go back out. Inside the AWS account are three components in a row. On the left, the Recorder, storing the referral together with the rule version in force at the time. In the middle, the Qualifier, asking whether it is earned yet and, if held, why. On the right, the Runner, producing one run and one statement each. A note at the bottom says the recorder stamps the rules, and nothing downstream can apply a newer version.AWS ACCOUNTReferrerswith a linkand a statementOrders and refundsthe existing systemsPayments outon a stated dayRecorderreferral + the ruleversion at the timeQualifierearned yet?held? why?Runnerone run,one statement eachreferralswhat happenedpayments andstatementsThe recorder stamps the rules. Nothing downstream can apply a newer version.
Fig 1. Three things outside the account, three pieces inside it. The stamp in the first box is what makes the whole thing defensible when the programme terms change.
  • Database
  • Machine learning
  • People

The stamp is the whole design

Referral terms change. The commission goes from twenty pounds to fifteen, a product gets excluded, a minimum order value appears. Every one of those changes is legitimate, and every one of them creates the same question: what happens to the referral somebody made last week under the old terms?

The answer has to be that it pays under the old terms, and the only way to guarantee that is to write the rule version onto the referral when it is created and to have no code path anywhere that reads the current rules for an existing referral. It is a small amount of engineering that prevents the single most damaging kind of dispute.

What runs (the inside)

  • The recorder. Captures the referral, who made it, when, and which published rule version applies. Part 2.
  • The qualifier. Decides when a referral has actually been earned, and holds the ones that need a person. Parts 3 and 4.
  • The runner. Pays on a stated day and produces a statement per person, including the held items. Part 5.

One referral, end to end

One referral from creation through to paymentA horizontal row of five boxes joined by arrows. Referral made: rules version four stamped. They order: on day three. Refund window: closes on day seventeen. Payable: twenty pounds, under version four. Paid: on the next run, with a statement. A note says rules version five arrived on day nine and made no difference to this one, and that is the point.ONE REFERRAL, END TO ENDReferral maderules v4 stampedThey orderday 3Refund windowcloses day 17Payable£20, under v4Paidnext run, with a statementRules v5 arrived on day 9 and made no difference to this one. That is the point.
Fig 2. The same system as one line. The note is the behaviour that makes the programme trustworthy and it costs one stored field.
  • Machine learning
  • Management
  • Front-end & mobile
  • People

In plain words

Somebody shares their link. A friend clicks it and orders three days later. The referral was recorded when the link was clicked, stamped with rules version four, which said twenty pounds on any order over fifty.

On day nine the business drops the commission to fifteen pounds. Version five is published, dated, and applies to referrals made from that point. This referral was made under version four, so it stays at twenty.

On day seventeen the refund window closes with no refund, and the referral becomes payable. On the next payout run it is paid, and the referrer gets a statement that says: one referral, ordered 3 August, qualified 17 August, twenty pounds, rules v4. If they had a second referral being held, that would be on the same statement with the reason next to it.

Design rules that shaped every decision

  • Stamp the rule version at creation. Never read current rules for an old referral.
  • Payable means the money is safe, not that somebody signed up.
  • A hold is always visible to the person, with a reason and a way to respond.
  • Every payout produces an itemised statement, including zero-payment runs.
  • The event log is append-only. A referral’s history is never rewritten.
  • No automatic clawback from a future payout without telling the person first.

Why this shape

The distinguishing feature of this system compared to most of the others in this series is that its outputs are other people’s money, and people notice money. A scheduling system that is wrong once a month is annoying; a payout system that is wrong once a month generates a permanent reputation.

That pushes the design towards conservatism in the payment direction and openness in the information direction: pay later than feels good, hold when unsure, and tell people everything about both. Almost every complaint about a referral programme is about silence rather than about the amount.

The next four posts walk through each piece: how a referral is recorded, when it becomes payable, how fraud is handled without punishing everyone, and how a disputed payout gets resolved. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts