A referral counter is never just a counter

The first referral system in my head looked more or less like this:

Beautiful. Two lines, job done.

Then reality arrived

Unfortunately, the world around those two lines immediately started asking questions. What if the person never confirms the email address? What if the browser retries after a timeout, even though the first request succeeded? What if two records belong to the same person? What if a referral is rejected later or somebody from the team corrects a mistake manually?

A number without a story is useless

At that point a number such as 17 referrals tells me only the current result. It does not tell me why the result is 17, and that difference becomes important the moment a reward depends on it.

A click is not a referral

The first change was to stop treating a click as a referral. A click is useful telemetry. Registration is an event. The referral itself is a campaign-scoped relationship between two stable identities. Email addresses can be corrected, verification can arrive later and requests can repeat, but that relationship should not become a new person every time something around it changes.

The lifecycle became explicit

The lifecycle became explicit: created, waiting for verification, verified, eligible, rewarded or rejected. The visible counter is derived from those records. It is convenient for the website, but it is no longer the source of truth.

Keep the facts, not just the total

I also keep the facts that changed the state: the referral was created, verified, rejected, rewarded or revoked. Thanks to that I can answer much better questions: which referral changed the number, whether a retry repeated the operation, why a reward appeared and whether I can rebuild the current state after changing a rule.

This may sound like a lot of machinery around a link somebody sends to a friend. It is. :) But the link is the easy part. Identity, verification and history are the system.

That was the moment CrowdRelay stopped being a counter and started becoming something I could actually trust.