Referral wiring

Buttondown-first referral attribution.

This is the implementation checklist for turning the static invite links into auditable referral metadata and a public leaderboard. It is prep only: no subscriber email, reward fulfilment or public leaderboard refresh happens from this page.

Do not publish standings, contact prize winners, send subscriber email or fulfil sponsor rewards until Buttondown attribution is live and the editor approves launch.

Test subscribe routeLeaderboard shellShare routePrivate ledger schema

Buttondown metadata

Fields to pass or derive when the live account is approved and credentials exist.

OpenreferrerHidden subscribe-form field populated from ?ref= or localStorage. This stays private.Openreferral_sourceRoute or campaign label such as share-page, facebook-organic, whatsapp or forwarded-email. This stays private.Openfirst_seen_pathLanding path where the referral code was first observed. This stays private.Opensignup_regionDefault Brighton and Hove; override only after reader self-identifies another useful local area. This stays private.Openreward_statuspending, verified, credited, withheld or sponsor-prize-ready. This stays private.

Live wiring test matrix

Run these with internal-only addresses before any subscriber email, public leaderboard refresh or reward promise.

Test scenario

direct website signup

URL: /subscribe/?ref=test-direct

Expected metadata: referrer=test-direct, referral_source=subscribe-page, first_seen_path=/subscribe/, signup_region=Brighton and Hove

Pass condition: Internal test subscriber appears in Buttondown with all metadata intact and no public leaderboard change.

Test scenario

share-page signup

URL: /share/?ref=test-share

Expected metadata: referrer=test-share, referral_source=share-page, first_seen_path=/share/, signup_region=Brighton and Hove

Pass condition: Referral code persists from share page to subscribe route and survives Buttondown test submission.

Test scenario

forwarded email or social link

URL: /?ref=test-social

Expected metadata: referrer=test-social, referral_source=landing-page, first_seen_path=/, signup_region=Brighton and Hove

Pass condition: Landing-page referral is stored locally, reused on subscribe, and visible only in private metadata.

Test scenario

no referral code

URL: /subscribe/

Expected metadata: referrer=, referral_source=subscribe-page, first_seen_path=/subscribe/, signup_region=Brighton and Hove

Pass condition: Signup succeeds without inventing a referrer and is excluded from referral scoring until moderation.

Private leaderboard ledger

Public standings should be backed by a private, reviewable ledger rather than raw Buttondown exports.

Opensubscriber hashPrivate ledger column used for moderation, scoring and audit before any public refresh.Openreferrer codePrivate ledger column used for moderation, scoring and audit before any public refresh.Openverified referral countPrivate ledger column used for moderation, scoring and audit before any public refresh.Openarea tagPrivate ledger column used for moderation, scoring and audit before any public refresh.Openfirst seen pathPrivate ledger column used for moderation, scoring and audit before any public refresh.Openlast credited atPrivate ledger column used for moderation, scoring and audit before any public refresh.Openreward statusPrivate ledger column used for moderation, scoring and audit before any public refresh.Openmoderation notePrivate ledger column used for moderation, scoring and audit before any public refresh.

Manual refresh sequence

Use this until Buttondown webhooks and an automated scorer exist.

OpenStep 1Export confirmed Buttondown subscribers with referral metadata after credentials exist.OpenStep 2Hash subscriber emails before storing anything used for leaderboard scoring.OpenStep 3Apply fraud controls and document every manual override.OpenStep 4Regenerate the static leaderboard from verified counts only.OpenStep 5Confirm internally for approval before publishing standings or contacting reward recipients.

Abuse controls

Referral growth should reward useful local spread, not fake signups.

OpenFraud controlCount confirmed Buttondown subscribers only.OpenFraud controlWithhold self-referrals, obvious aliases and disposable email domains.OpenFraud controlReview same-IP or same-device clusters before public refresh.OpenFraud controlRequire plausible Brighton and Hove local intent before prize or sponsor reward eligibility.OpenFraud controlNever publish raw emails, subscriber IDs or private referral tokens.

Failure-mode stops

If any of these happens, keep the leaderboard static and resolve the Buttondown path before launch.

OpenStop conditionStop if Buttondown strips or renames any referral metadata field during test signup.OpenStop conditionStop if a referral code appears in public HTML, analytics URLs or exported public leaderboard JSON.OpenStop conditionStop if unsubscribed, unconfirmed or duplicate test subscribers can increase the verified referral count.OpenStop conditionStop if the private ledger requires raw email addresses, Buttondown subscriber IDs or private tokens in the repo.OpenStop conditionStop if welcome automation, public standings or reward copy can be triggered without separate editor approval.