allanninal.dev/build

Part 3 of 7 · Referral tracker series ~8 min read

How a referral gets attributed

Between a shared link and a paid reward sit three separate events: a click, a sign-up, and a conversion. This post is about tying them together honestly — how the redirect logs a click, how a sign-up is attributed to the last referrer inside the window, and why the reward stays pending until the friend actually buys.

Key takeaways

  • A tap on the link hits a Lambda Function URL that logs the click and 302-redirects to the sign-up page in a few milliseconds.
  • The click drops a short-lived attribution token whose lifetime is the last-touch window, so old clicks expire and stop counting.
  • On sign-up, the most recent valid click wins — last touch — and the referrer named on that code is credited.
  • Attribution opens a pending referral; a click and a sign-up on their own pay nothing until a real conversion follows.
  • A sign-up with no click in the window, or a code that’s been retired, is simply unattributed — nobody is credited by accident.

Three events, not one

It’s tempting to think of a referral as a single thing, but honestly attributing one means keeping three separate events apart and only joining them when each is real. First a click: the friend taps the shared link. Then a sign-up: they create an account. Then, later and by no means always, a conversion: they actually buy. Plenty of clicks never sign up, and plenty of sign-ups never buy. If you pay on the click you reward curiosity; if you pay on the sign-up you reward an email address. The reward belongs to the conversion — but to know whom to reward when it finally happens, you have to have quietly followed the trail from the very first tap. This post is about laying that trail down honestly.

The design keeps a firm line: attribution decides who would be credited if this converts, and nothing more. It opens a pending referral and waits. The money doesn’t move here — that’s Part 4 — but everything Part 4 needs to pay the right person, exactly once, is assembled here.

The redirect that logs a click

The shared link points at one Lambda Function URL — refer.freshbox.uk/r/7QK2A resolves to a function, not a web server. When a friend taps it, the function does the smallest possible amount of work and gets out of the way: it looks up the code, records a click, sets a short-lived attribution token, and returns a 302 redirect to the real sign-up page. All of that takes a few milliseconds, so the link behaves exactly like any other short link — tap, arrive. Nothing about logging the click is allowed to make the visitor wait; a slow referral link is one nobody clicks twice.

The attribution token is the quiet mechanism that ties a future sign-up back to this click. When the redirect fires, it sets a token — a first-party cookie on the store’s domain, and the same value appended to the redirect URL as a fallback for when cookies are blocked — that says “this visitor last touched code 7QK2A”. Crucially, that token is given a lifetime equal to the last-touch window: 30 days, say. After that it expires on its own. The click itself is written to a click log with a matching TTL, so the record and the token die together, and a tap from two months ago can’t reach forward and claim a sign-up today.

Attribution: a click logged behind a redirect, then a sign-up matched to the last-touch code inside the window The diagram has two lanes inside a dotted AWS account container. The top lane is the click path: an external box “Friend taps link” sends an arrow into a box “Redirect (Function URL)”, which reads the DynamoDB codes table to resolve the code, writes a row to a DynamoDB click log with a TTL equal to the window, sets a short-lived attribution token, and returns a 302 arrow to an external box “Sign-up page”. The bottom lane is the sign-up path: an external box “Store sends sign-up event”, carrying the attribution token, sends an arrow into a box “Attributor Lambda”. The attributor reads the click log for the most recent valid click within the window — last touch — and follows a decision: if a valid click is found, an arrow goes to a box “Open pending referral” that writes the DynamoDB referrals table crediting the referrer named on that code; if no click is found within the window or the code is retired, an arrow goes to a box “Unattributed” that credits nobody. A note reads: last touch inside the window wins; a click and a sign-up alone pay nothing — the referral stays pending until conversion. AWS account Friend taps link /r/7QK2A Redirect Function URL, 302, set token DynamoDB codes (resolve) DynamoDB click log write, TTL = window Sign-up page visitor arrives 302 Store sign-up carries the token Attributor Lambda find last-touch click DynamoDB click log most recent in window Open pending referral credit the referrer match Unattributed nobody credited no click Last touch inside the window wins; a click and a sign-up alone pay nothing — the referral stays pending until conversion.
Fig 3. Attribution in two lanes. The redirect logs a click with a window-length TTL and sets an attribution token, then sends the visitor on. When the store reports a sign-up carrying that token, the attributor finds the most recent valid click and opens a pending referral for that referrer — or leaves it unattributed if nothing valid is in the window.

Last touch, inside the window

When the store reports a sign-up, it carries whatever attribution token the visitor arrived with, and the attributor uses it to answer one question: which referrer, if any, gets the credit? The rule is last touch — the most recent valid click within the window wins. If Mara tapped a link from Dan a fortnight ago and another from her colleague Sam yesterday, Sam gets the credit, because his was the touch that actually brought her back to sign up. Last-touch is the honest default for word of mouth: it rewards the nudge that landed, not the one that happened to be first, and it’s simple enough to explain to a customer who asks why they were or weren’t credited.

“Valid” is doing real work in that sentence. A click only counts if it’s inside the window — the TTL guarantees an expired one isn’t even in the table — and if the code it points at is still live. A sign-up that arrives with a token for a retired code, or with no token at all, or whose only clicks fell outside the window, is simply unattributed: the account is created as normal and nobody is credited. That’s the right outcome, not a failure. Crediting nobody is always safer than crediting the wrong person, and a referral programme that occasionally misses a genuine referral is far less damaging than one that pays out on ghosts.

Pending, and waiting

A successful attribution doesn’t pay anyone; it opens a pending referral. That record ties three things together — the referrer from the code, the newly signed-up friend, and the reward terms pinned back at mint time — and it sits in the pending state until one of two things happens. Either the friend converts, and Part 4 credits both sides exactly once; or they never do, and the referral quietly expires when its own window elapses (the expiry sweep in the engineering reference does the tidying). Keeping the reward pending is what makes the whole programme honest: the click showed interest and the sign-up showed intent, but only the conversion shows a real customer, and only a real customer is worth a reward. Everything up to here has just made sure that when the conversion arrives, the system already knows exactly whose reward it is.

Design rules that shaped attribution

  • The redirect is sacred. Log the click, set the token, and 302 in milliseconds — the link must never feel slow.
  • The token lives for the window. Click records and tokens share a TTL, so an expired click can’t reach forward and claim a sign-up.
  • Last touch wins. The most recent valid click in the window is credited — the nudge that actually landed, not the first one.
  • Credit nobody before the wrong body. No click, no token, or a retired code means unattributed — never a guessed referrer.
  • Attribution opens, it doesn’t pay. A sign-up only ever creates a pending referral; the money waits for a real conversion.
All posts