Design a Referral & Affiliate System

Problem statement

Design a referral and affiliate platform for an e-commerce marketplace. Consumers and external partners share unique links or codes. When a shopper clicks one and later converts — signup, first order, or any qualifying purchase — the platform must attribute that conversion to the correct partner, compute the reward under a versioned policy, credit it to a ledger, and eventually pay it out, while blocking self-referrals, cookie stuffing, click spam, and duplicate payouts.

The hard part is not generating links. The hard part is that this system converts noisy, adversarial, privacy-constrained click telemetry into money movements that must be exact. A marketing dashboard can be eventually consistent. A commission ledger cannot post the same conversion twice, and it cannot silently drop a legitimate one. The design therefore separates three concerns that weak answers merge: capture (recording clicks fast and durably), attribution (deciding which partner owns a conversion under policy), and settlement (posting, holding, clawing back, and paying commissions with financial integrity).

Why the problem is distinctive

A recommendation system can be wrong and lose a click. An attribution system that is wrong moves money to the wrong party and creates legal exposure. Three pressures collide: (1) privacy erosion — Safari ITP, iOS ATT, and third-party cookie deprecation destroy the classical cookie-tracking model; (2) adversarial partners — affiliates are paid per outcome, so sophisticated actors stuff cookies, inject clicks, and refer themselves; (3) financial exactness — commissions are a liability on the balance sheet, subject to tax reporting (W-9/W-8, 1099-NEC in the US), clawbacks on refunds, and payout regulation.

Public operating baseline versus design assumptions

Public evidence shows the category is mature. Amazon launched Associates in 1996 as one of the first large-scale affiliate programs; public reporting describes it as paying affiliates over a billion dollars per year, with a 24-hour attribution cookie and a 90-day window when items are added to cart. Rakuten Advertising's annual benchmark reporting places US affiliate marketing spend around $16-17 billion in 2024. Dropbox's two-sided referral program grew signups from roughly 100,000 to 4,000,000 in 15 months, a figure Dropbox has published. These are cited context figures, not requirements for our fictional system.

For capacity planning this answer explicitly assumes: 500,000 registered partners (about 450,000 consumer referrers and 50,000 content affiliates), 25 million tracked clicks per day average with a 5x event peak, 2 million marketplace orders per day of which 8% qualify for program attribution, and monthly payout runs covering roughly 120,000 eligible partners. Unless tied to a citation, every number here is a stated design assumption, target, or budget.

The four architectural planes

1. Capture plane: redirect resolution, first-party cookie and token issuance, click event ingestion, postback intake.
2. Attribution plane: identity resolution, window enforcement, deterministic-first source ranking, conversion matching.
3. Ledger plane: double-entry commission postings, holds, clawbacks, payout batches, tax documents.
4. Trust plane: fraud scoring, self-referral graph analysis, compliance policy, audit evidence, dispute handling.

A strong answer keeps these planes separate: the capture plane may shed load under pressure, the ledger plane may never lose or duplicate a posting, and the trust plane may hold money but must never silently rewrite history.