Skip to content
allanninal.dev/build
Collaborate

Part 2 of 7 · Referral payout runner series ~5 min read

How a referral gets recorded

The referral is created before anybody knows whether it will be worth anything, which is the awkward property that shapes the whole record: you have to write it down at the moment it happens and then wait to find out if it mattered.

Key takeaways

  • The referral is created at the click, with the rule version and timestamp.
  • The attribution window is published, finite, and applies from the click.
  • First click wins, and the rule is stated in the terms rather than assumed.
  • Self-referral is detected at recording, not at payout.
  • The record is append-only; a referral is corrected by a new event, never an edit.

The moment of record

How a referral link click becomes a recorded referralA vertical chain of five steps entered by a box labelled Somebody clicks a link carrying a referrer's code. Step one asks whether the code is live and not suspended; if not it exits to No referral, and the visit is treated as normal. Step two asks whether this person has already been referred by anyone within the window; if so it exits to First click keeps it, as stated in the terms. Step three asks whether the referrer and the referred person are the same; if so it exits to Self-referral, recorded but never payable. Step four creates the referral in a pending state. Step five stamps the rule version, version four published on the twelfth of July. A note says everything after this reads the stamp, and nothing reads the current rules.AWS ACCOUNTSomebody clicks a linka referrer's codeIs the code live?not suspendedNo referraland the visit is normalnoAlready referred?by anyone, in windowFirst click keeps itstated in the termsyesSame person?referrer and referredSelf-referralrecorded, never payableyesCreate the referralpendingStamp the rule versionv4, published 12 JulEverything after this reads the stamp. Nothing reads the current rules.
Fig 1. How a click becomes a recorded referral. The last box is the one that prevents the worst class of dispute two months later.
  • Compute
  • App integration
  • Machine learning
  • Security & identity
  • Management

Why first click and not last

Two people can plausibly refer the same customer, and whichever rule you choose will occasionally feel unfair to somebody. First click is the better default for a referral programme — unlike advertising attribution — because the referral is a personal act and the first person to make it did the work of the recommendation.

What matters more than the choice is that it is written in the published terms in one sentence, so the conversation with the second referrer is about a rule they agreed to rather than about a decision somebody appears to have made about them.

The window is published

A referral does not last forever. Thirty, sixty or ninety days from the click is typical, and the number matters less than it being stated and applied consistently. An unpublished window is discovered by referrers exactly once, at the moment they find out they were not paid.

The window runs from the click, not from the signup, and it is stamped alongside the rule version so that shortening it later cannot retroactively expire referrals that were still live under the old terms.

Append-only, always

The append-only event log of a single referralA horizontal row of five boxes. Created: third of August, rules version four. Order linked: sixth of August, one hundred and twenty pounds. Held: seventh of August, address match. Released: ninth of August, by a named person. Paid: first of September, in the September run. A note says five rows, none of them edited, and the state is derived rather than stored as the truth.ONE REFERRAL'S EVENT LOGcreated3 Aug, v4order_linked6 Aug, £120held7 Aug, address matchreleased9 Aug, by namepaid1 Sep, run 2026-09Five rows, none of them edited. The state is derived, never stored as the truth.
Fig 2. A referral’s full history as events. Deriving the state from the log rather than storing it means the answer to “why is this held” always exists.
  • Management
  • Front-end & mobile
  • People

The temptation is a status column that gets updated. It works until somebody asks why a referral that was held in August was paid in September, and the answer is a value that was overwritten and a timestamp that says only when it last changed.

Events cost slightly more storage and remove an entire class of unanswerable question. For a system handling other people’s money that is not a close call.

Self-referral at recording

Catching the obvious cases — same account, same email, same payment method — at the moment of recording is better than catching them at payout, because the record then says self-referral from the start rather than looking like a payment that was withheld.

It also means the referrer finds out immediately if they misunderstood the programme, which for a good proportion of them is exactly what happened. Somebody ordering through their own link is more often confused than dishonest.

Next: when a referral becomes payable.

All posts