allanninal.dev/build

Part 1 of 7 · Referral tracker series ~10 min read

A referral tracker on AWS for a few dollars a month

Word of mouth is the cheapest customer a small business ever gets, and almost nobody tracks it. This post walks through the design of a small serverless system that gives every customer their own referral link, follows the friend they send from click to sign-up to first purchase, and — only then — credits both sides exactly once, with the self-referrals and dupes quietly filtered out.

Key takeaways

  • A customer asks for a referral link; the system mints a unique code and one Bedrock call writes a shareable invite in your voice.
  • A tap on the link is logged behind a fast redirect, so word of mouth becomes something you can actually see and credit.
  • A sign-up is attributed to the referrer on a last-touch window; the reward stays pending until the friend genuinely converts.
  • On conversion, both sides are credited exactly once and thanked — self-referrals, dupes, and empty codes are filtered out first.
  • Designed on AWS for about $1.70/month at roughly 200 clicks and 20 conversions. Every decision is plain Python; the model only writes words.

The whole system on one page

Before any code, here’s the shape of what we’re designing. Nearly every small business has customers who’d happily recommend them — the meal-prep subscriber who won’t shut up about it at work, the regular at the barber’s, the neighbour who watched the window cleaner do next door. The trouble is that goodwill vanishes the moment it’s spoken: there’s no link, no record, no way to say thank you to the person who actually sent someone. The system below catches that moment and makes it trackable. A customer asks for their link, a friend they send taps it, and if that friend becomes a real customer, both of them are rewarded — automatically, and only once.

System architecture: a referrer and a friend outside, the store and your team around it, four pieces inside AWS At the top, three external boxes in a row. Far left, “Referrer & friend” — the existing customer who requests a link and shares it, and the friend who clicks it, signs up, and eventually buys. Centre, “Store & checkout” — the sign-up page and the checkout that fires a conversion webhook when the friend makes a first purchase, plus the reward catalogue and the settings that define the window and payouts. Far right, “Your team” — the person who reviews anything the fraud screen holds. Each connects by an arrow to the AWS account container below. The referrer and friend receive the link and the reward and generate clicks and sign-ups; the store sends sign-up and conversion events in and fulfils the actual reward; your team receives fraud reviews. Inside the AWS account are four components. Left, Mint & invite — issues a unique code, records the referrer and reward terms, and makes one Bedrock call to write a shareable invite. Next, Attribute — a Function URL redirect logs each click and, on sign-up, credits the last referrer inside the window, holding the reward as pending. Next, Reward — on a confirmed conversion it credits both sides exactly once and makes one Bedrock call to write two thank-you notes. Below the middle sits Screen — the fraud check that blocks self-referrals, dedupes repeat conversions, and holds codes behaving like bots, fed by both the attribute and reward paths. Arrows flow left to right through mint, attribute, and reward, with branches down into screen. A note at the bottom reads: it credits each referred customer exactly once, to both sides, and quietly blocks self-referrals, dupes, and codes shared into the void. Referrer & friend share, click, sign up, buy Store & checkout sign-up + conversion events Your team where fraud reviews land link & reward out, clicks in events held referral to review AWS account Mint & invite unique code, reward terms, one Bedrock invite Attribute redirect logs click, last-touch on sign-up Reward both sides, exactly once, one Bedrock thank-you link convert Screen self-referral, dupes, velocity check each before payout flag at source It credits each referred customer exactly once, to both sides, and quietly blocks self-referrals, dupes, and codes shared into the void.
Fig 1. Three things outside, four pieces inside AWS. A customer requests a link; Mint & invite issues it, Attribute logs the click and credits the last referrer on sign-up, and Reward credits both sides once the friend converts. Everything a payout depends on passes through Screen first.

What you set up once (the outside)

  • Your store and checkout. Wherever a new customer signs up and makes their first purchase — a subscription app, a booking page, a shop. It needs to do three things: send a sign-up event when someone creates an account (carrying whatever referral token they arrived with), fire a conversion webhook when that account makes its first real purchase, and accept a reward back — a credit, a discount code, a free box — so the system can fulfil what it promises. You point these at one AWS URL and store the signing key in Secrets Manager. This is the trigger for attribution and reward, and it’s covered in Parts 3 and 4.
  • The reward terms and voice. A small settings doc: what each side gets (say £10 credit for the referrer and £10 off the friend’s first box), how long the last-touch window runs, the daily velocity limits, and the business’s voice for the invite and thank-you copy. This is where you decide the shape of the offer; the system just enforces it. The reward catalogue — the actual codes or credits it hands out — lives with the store.
  • Your team. The person who looks at anything the system deliberately won’t pay on its own — a referral held by the fraud screen, usually because it looks like a self-referral or a code behaving like a bot. They get an email with the referrer, the referred customer, and exactly why it was held, and they approve or reject it. The system never pays a held referral automatically; a human makes that call.

What runs on every referral (the inside)

  • Mint & invite. A customer asks for their link — a tap in the app, a click on the account page. One Lambda mints a short, unique, collision-proof code, records who it belongs to and the reward terms in force, and makes a single Bedrock Haiku 4.5 call to write a shareable invite in the business’s voice. The link goes back to the customer to share. This is Part 2.
  • Attribute. When a friend taps the link, the request hits a Lambda Function URL that logs the click and redirects them straight to the sign-up page in a few milliseconds. If that friend signs up, the system credits the most recent referrer inside the last-touch window and opens a pending referral. A click and a sign-up on their own pay nothing. This is Part 3.
  • Reward. When the referred person makes a genuine first purchase, the checkout fires a conversion webhook. The system confirms the referral is pending and eligible, credits both sides exactly once with a conditional write, fulfils the reward through the store, and makes one Bedrock call to write two short thank-you notes. This is Part 4.
  • Screen. The fraud lane that everything a payout depends on runs through: is the referred person really the referrer wearing a different hat? Has this friend already been rewarded once? Is one code suddenly spraying clicks and sign-ups like a script? Self-referrals and dupes are blocked outright; anything merely suspicious is held for a person. This is Part 5.

In plain words

Dan has had a FreshBox meal-prep subscription for a few months and keeps recommending it. He taps “refer a friend” in the app; a second later he has a link — refer.freshbox.uk/r/7QK2A — and a ready-written message: “I’ve been getting FreshBox for a while and it’s genuinely saved my weeknights. Here’s £10 off your first box if you fancy trying it.” He sends it to his friend Mara. On Tuesday she taps the link out of curiosity; the redirect logs the click and drops her on the sign-up page. On Thursday she comes back and signs up — the system looks over the last-touch window, sees Dan’s was the most recent link she touched, and opens a pending referral crediting him. Nothing is paid yet. The following week her first box ships and the checkout fires a conversion. Now both sides are credited exactly once: Dan gets £10 off next month, Mara’s £10 welcome discount is confirmed, and each gets a warm thank-you. Nobody at FreshBox touched a thing.

A week later a different account tries the same code from Dan’s own phone, on the same card he pays with, under a new email. That isn’t a referral — it’s Dan trying to refer himself for a second £10. The system matches the new sign-up’s payment fingerprint and device to Dan’s existing account, recognises a self-referral, and blocks it before a penny moves. It doesn’t email Dan an accusation; it simply declines to pay and records why, and if anything about the case is genuinely ambiguous it lands in front of a person rather than being guessed at. The honest referral pays instantly; the self-referral quietly doesn’t.

Design rules that shaped every decision

  • Pay on conversion, not on hope. A click or a sign-up earns nothing; only a genuine first purchase triggers a reward.
  • Both sides, exactly once. Each referred customer credits the referrer and themselves a single time — a repeat webhook never double-pays.
  • Last touch wins, inside a window. The most recent referrer within the window gets the credit; stale clicks expire and pay nobody.
  • The model only writes words. The invite and the thank-you are phrased by Bedrock; every attribution and fraud decision is deterministic.
  • Assume it’ll be gamed. Self-referrals and dupes are blocked, and anything spraying like a bot is held for a human, not paid.
  • The redirect stays instant. Logging a click never slows the link down; the visitor is on their way in milliseconds.

Why this shape

Most small businesses handle referrals one of three ways: they don’t — goodwill evaporates unrecorded; they run an honesty-box “mention my name” scheme that nobody remembers to apply; or they buy a full referral SaaS with a monthly seat price that only makes sense at real scale. The first leaves money on the table every week. The second is untrackable and unfair — the customer who actually sent three people gets nothing. The third is a fixed bill for something a barber or a window cleaner uses a dozen times a month. The gap is a cheap, honest way to mint a link, follow it, and pay out fairly — and nothing in a typical small shop fills it.

The shape above fills exactly that gap and nothing more. It leans on the store you already run for the sign-up and conversion events, keeps the reward terms as a setting you control, and adds a small system that turns each customer’s recommendation into a trackable link and a fair payout. The common case — a real friend who really subscribes — runs end to end with no human involved. The few that are dubious are pulled out before any money moves and put in front of a person, with the whole story attached.

The next four posts walk through each piece in turn: how a referral link gets minted, how a referral gets attributed, how a reward gets issued, and how referral fraud gets caught. One diagram per post. A cost breakdown and a final engineering reference at the end.

All posts