allanninal.dev/build

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

How a referral link gets minted

A referral programme is only as good as the link a customer can actually share. This post is about minting that link: how a request becomes a unique, collision-proof code tied to the right referrer, how one small model call turns it into an invite the customer is happy to send, and why every fact about the reward is pinned at mint time, not later.

Key takeaways

  • Minting starts when an existing customer asks for a link — a tap in the app or on the account page — never on its own.
  • The code is short, random, and collision-proof: a conditional write claims it, so two customers can never be handed the same one.
  • The referrer, the reward terms, and the window are pinned onto the code at mint time, so later changes never move an in-flight referral’s goalposts.
  • One Bedrock call writes a shareable invite in the business’s voice; the link itself is injected by code, never typed by the model.
  • A customer who already has an active code is handed the same one back, so a nervous double-tap doesn’t litter the table with duplicates.

Everything downstream depends on one small artefact: a link a customer is actually willing to send. Get it wrong and the whole programme stalls before it starts — an ugly code nobody trusts, a message so corporate it makes the sender cringe, or a link that collides with someone else’s and credits the wrong person. So minting gets its own step, and it does three things carefully: it makes a code that can only ever mean one referrer, it pins down exactly what reward that code promises, and it writes an invite the customer is happy to paste into a message to a friend.

Minting is always triggered by a real customer asking. A subscriber taps “refer a friend” in the FreshBox app; a regular scans the QR on the mirror at the barber’s; the window cleaner’s customer clicks a link in their receipt email. That request carries the customer’s identity from the store, which is how the system knows whose code this is. The system never mints a code nobody asked for, and it never invents a referrer — a code with no owner could credit anyone, which is exactly the hole a fraud programme can’t have.

A code that means one person

The code is short on purpose — five or six characters from an unambiguous alphabet, no easily-confused 0/O or 1/l — because it’s going to be read aloud, typed on a phone, and printed on a card in the window cleaner’s van. Short codes mean a small chance that two random draws collide, so the system doesn’t trust to luck: it generates a candidate and claims it with a conditional write to the codes table — write this item only if this code doesn’t already exist. If the claim fails, it draws another and tries again. The first writer wins; nobody is ever handed a code that already belongs to someone else.

At the same moment the code is claimed, the system pins the facts that make it mean something: which customer owns it, and the reward terms in force right now — what the referrer gets, what the friend gets, and how long the last-touch window runs. Pinning these at mint time is deliberate. If FreshBox later cuts the referrer reward from £10 to £5, a code Dan minted last week still pays the £10 it promised when he shared it; the offer a customer sent in good faith is the offer that’s honoured. The code carries its own terms so nothing that changes later can quietly move the goalposts on a referral already in flight.

Minting a link: a request, an existing-code check, a claimed unique code, one Bedrock invite, then the link back On the left, an external box “Customer asks for a link” sends an arrow into a box “Mint Lambda” inside a dotted AWS account container. The mint Lambda first checks a DynamoDB codes table for an existing active code for this customer; if one is found, an arrow labelled reuse goes straight to the output. Otherwise it runs a loop: generate a short candidate code, then attempt a conditional write to the codes table that claims it only if it does not already exist; a collision loops back to generate again, and a successful claim continues. On claim, the referrer id and the reward terms and window are written onto the code item. Next an arrow goes to a Bedrock box labelled Claude Haiku 4.5, Global inference, which returns invite copy containing a link placeholder rather than a real URL. An arrow goes to a box “Inject link” where code replaces the placeholder with the real short URL. Finally an arrow goes out to a box “Link + invite to the customer”. A note reads: the code is claimed with a conditional write so it can only mean one referrer, and the reward terms are pinned at mint time. Customer asks for a link AWS account Mint Lambda claim + pin terms Generate code short, unambiguous DynamoDB codes conditional write, claim if new collision, retry has active code? reuse it Bedrock Haiku 4.5, Global invite Inject link placeholder → real URL draft Link + invite back to the customer The code is claimed with a conditional write so it can only mean one referrer; the reward terms are pinned at mint time.
Fig 2. Minting a link. An existing active code is handed straight back; otherwise a short candidate is drawn and claimed with a conditional write, retried on collision, then stamped with the referrer and the reward terms. One Bedrock call writes the invite, code injects the real URL, and the link goes back to the customer.

One code per customer, not per tap

Before it draws a fresh code, the mint function checks whether this customer already has an active one. Most do, after the first time — and a referral link is more useful the longer it stays stable, because a customer might paste it into a WhatsApp group today and a work Slack next month, and both should credit the same person. So a customer’s code is durable: ask twice and you get the same link back, not a second one. This also quietly defends the table against the nervous double-tap and the impatient retry, which would otherwise scatter half a dozen live codes for one person and make attribution ambiguous later. One customer, one active code, handed back as many times as they ask.

There’s one deliberate exception: if a customer’s code has been retired — because it was implicated in abuse, say, or the customer left and came back — a fresh mint issues a new one and the old code simply stops attributing. Retirement is a state on the code, not a deletion, so the click and referral history tied to the old code stays intact for the record even though it can no longer earn.

The invite, in your voice

The last thing minting does is write the message the customer will actually send, and this is the one place a model runs at mint time. A single Bedrock Haiku 4.5 call is handed a narrow brief: the business name and voice notes from the settings doc, the friend-side reward (“£10 off your first box”), and a placeholder where the link will go. It writes one short, warm invite that sounds like the business and doesn’t oversell — the sort of thing a real person would be happy to paste under “you should try this”. Haiku is right for the job precisely because it’s small: a sentence or two, in a set tone, with nothing to reason about.

The link itself is never written by the model. Bedrock emits a token like {{link}}, and the code substitutes the real short URL — refer.freshbox.uk/r/7QK2A — afterwards. A language model is perfectly capable of subtly mistyping a URL or “tidying” it, and a broken referral link is the one mistake that quietly wastes the whole invite: the friend can’t click, the click can’t be logged, nobody gets attributed. By keeping the link out of the model’s hands and injecting it deterministically, the link is always exactly right, and the draft is checked for length and a single link before it goes out. If the model is slow or the draft fails a check, a plain fixed template is sent instead — less charming, always correct. The model gets the warmth; the code keeps the guarantee.

Design rules that shaped minting

  • Only on request, always owned. A code is minted when a real customer asks, and it always names exactly one referrer.
  • Claim, don’t hope. A conditional write claims each code so two customers can never be handed the same one.
  • Pin the terms at mint. The reward and window travel on the code, so a later change never moves an in-flight referral’s goalposts.
  • One durable code per customer. Ask twice, get the same link — stable to share, and no duplicate codes to confuse attribution.
  • The link is the code’s job. The model emits a token; the real URL is injected afterwards so it can never be mangled.
  • A template is always ready. If the model drifts or fails, a fixed correct invite goes out — the link is never held up by a bad draft.
All posts