#FE: Referral & Affiliate screens (from backend Phase 18)
Frontend spec for backend Phase 18 — Referral & Affiliate — requirements complete 2026-10-08, not built, and fully settled the same morning — its one open point (18.12) was answered minutes after the phase was published. V8 requirement The referral programme works as V7 did; the affiliate programme is handled entirely by Tolt, outside Central.
Sign-up — a Tolt code or a referral code is read from the link and saved; nothing is typed
Tolt (outside Central) — the affiliate's dashboard, links, commission rates and payouts
Central
referral page — your link, clicks, signups, approved referrals
Central
credit balance — the new user's credit at sign-up, the referrer's credit once approved
Admin → General (17.19) — referral on / off, both credit amounts, minimum payment, top referrers
i18n namespaces: referral.*, admin.referral.*.
#A. The affiliate side — nothing to build, and that is the spec
| # | Feature | Screen / control | Rules from the backend doc | Frontend notes |
|---|---|---|---|---|
| 18.1 | Sign-up tracking | No screen | Signing up from a Tolt affiliate link — by email or Google / GitHub — saves the Tolt code on the user (2.1) | Invisible by design. The code arrives in the link and is never typed, so the sign-up form needs no new field. Worth noting it covers the social routes too: the code must survive a round trip to Google or GitHub and back, which is the only frontend concern on this whole row |
| 18.2 | Payments | No screen | Central sends the Tolt code with the user's Stripe payments — ordinary payments and auto-recharge — and Tolt works out the commission. As V7: only users who signed up less than a year ago, and never server-credit payments | Three limits, and none of them belongs on a screen. The one worth knowing while building: commission follows Stripe only, while Central offers three gateways (D-5: Stripe, PayPal, Instamojo). A user paying by PayPal earns their affiliate nothing. That is the affiliate's problem, not the payer's, so nothing should be said on the payment screen — but nobody should "helpfully" add a gateway hint either |
| 18.3 | Everything else | No screen | Commission rates, the affiliate dashboard, links and payouts are managed in Tolt. Central has no affiliate dashboard, no commission slabs and no payouts | This deletes a whole proposed admin section. The frontend doc's A9 Admin: affiliate program was a V7 proposal waiting on the backend; the backend has now said there is nothing to wait for. It should be marked not in V8, not left pending |
| 18.4 | Tolt keys | Admin → settings | Program ID + token, set by the admin, stored encrypted (as 17.20) | Two write-only fields next to the other integration keys (17.20) — masked hint, never read back, a visible replace action. No test button is specified, unlike the mail keys, so none should be invented |
#B. The referral programme — the screens Central does own
| # | Feature | Screen / control | Rules from the backend doc | Frontend notes |
|---|---|---|---|---|
| 18.5 | Referral link | Referral page | Every user gets their own link (?r=CODE) and clicks are counted | A link with Copy as the primary action, and a click count beside it. Copy is the whole job, so make it the obvious button rather than burying it in a text field |
| 18.6 | The new user's reward | Sign-up result | Signing up through a referral link adds the new user's credit to their balance straight away. The referrer must be an active user | Instant, unlike the referrer's half — so the new user should see the credit on their balance from their first visit, and it should be named as referral credit on the billing screen rather than appearing as an unexplained amount. The active-referrer condition has no stated failure behaviour Open question: nothing says what the new user sees if the referrer's account is locked or expired |
| 18.7 | The referrer's reward | Referral page | A daily check: once the referred person has a plan and has paid at least the minimum amount, the referrer gets the referrer credit — once — plus an email | This is the number the screen must explain, not just display. A user with ten signups and no credit has not hit a bug: their referrals have not taken a paid plan yet. So the page should say the condition in one line next to approved, because without it the count looks broken. And because the check is daily, the page must not promise anything immediate |
| 18.8 | Referral page | Its own page | The user's link, clicks, signups and approved referrals | Four numbers and a link. No payout, no withdrawal and no balance of its own — the reward is credit, so it lands on the ordinary billing balance. That is the clearest difference from the affiliate programme and the reason this page stays small |
| 18.10 | Notifications | Existing notifications | "Referral credit received" goes through Phase 11. V7's "affiliate request / approved" emails are dropped | One event for the existing list. The two dropped emails are the last trace of the old built-in affiliate flow, which had an application to approve; Tolt has no such step, so nothing replaces them |
| 18.11 | Activity log | Existing activity log | The referral sign-up credit and the referrer credit are recorded | Two new entry types. Both are money arriving, so they belong with the billing entries rather than the account ones |
| 18.12 | Both codes at once | No extra screen | Settled 2026-10-08 (Jayshree): both count — they are separate rewards. The affiliate earns their commission in Tolt; the referral credits are given as normal. This is already how V7 behaves today | Nothing competes, so nothing needs deciding on screen — which is the simplest possible outcome and removes a branch the sign-up flow would otherwise need. It does overturn a rule written down elsewhere: the frontend doc still says "affiliate code wins", which described V7's built-in affiliate beating a referral. That system is gone and the Tolt code is stored separately, so the two rewards no longer meet. Reported for the flow doc |
#C. Admin
| # | Feature | Screen / control | Rules from the backend doc | Frontend notes |
|---|---|---|---|---|
| 18.9 | Referral settings | Admin → Referrals — two screens | On / off, the new user's credit, the referrer's credit and the minimum payment (named at 17.19), plus a top-referrers list. Placed an hour later by 17.2: "Referrals" is its own admin group, holding users and settings | This spec's first reading was wrong and is corrected here. When 18.9 landed it looked as though the top-referrers list was stranded inside 17.19's general settings, and this page said a league table beside four numeric inputs reads like a mistake. 17.2 then published the admin group list and Referrals is a group of its own — so the report gets its own users screen and the four amounts sit in settings. Exactly the split that was asked for, already decided |
#D. What a migrated user brings
| Rule | Frontend notes |
|---|---|
| Referral codes, clicks and referrals — approved and pending — carry over, and pending referrals can still earn the referrer their reward | So a migrated user's referral page is not empty, and a referral made in V7 can pay out in V8. The page needs no "since V8" caveat |
| Affiliates keep working in Tolt — nothing changes for them | Nothing to build, and nothing to explain in Central either |
| The old built-in affiliate data is not migrated — it moved to Tolt back in 2024 | So there is no legacy affiliate state to display anywhere, which is why 18.3 can be absolute |
#What this phase answers
| Open item | Answer |
|---|---|
| "Affiliate / referral is its own phase" — carried on Product overview, FE: Billing screens, FE: Account screens and D-23 | It is now a written phase (18.1–18.12) V8 requirement — and it splits in two: referral is Central's, affiliate is Tolt's |
| Does the referral programme survive V8? | Yes, as V7 — the link, the two credit rewards, the page and the admin settings are all specified. The answer 17.19 hinted at is now explicit |
| Does V7's built-in affiliate programme survive? | No. The apply form, approval step, commission slabs, monthly commission job, PayPal payouts, banners and custom links are not in V8 — Tolt replaced them, in production, in 2024 |
| What backs the sign-up form's "referral / affiliate code" field? | Both codes are real and both come from the link (18.1, 18.5) — so FE: Auth screens's pre-filled, read-only field is right, and the affiliate half simply has no screen behind it |
| Where does referral credit appear? | On the ordinary credit balance (18.6, 18.7) — it is credit, not a separate wallet, and it shows in the activity log (18.11) |
| If a user arrives with both a Tolt affiliate code and a referral code, which one counts? | Both — answered 2026-10-08 (18.12, Jayshree). They are separate rewards: the affiliate earns their commission in Tolt, and the referral credits are given as normal. This is already how V7 behaves today. It overturns the rule the frontend doc still carries — "affiliate code wins" — which described V7's built-in affiliate competing with a referral. That system is gone, the Tolt code is stored separately, and nothing competes any more |
| What is left on D-23's unscheduled list? | Only the AI assistant. Support tickets were cancelled earlier today, white label, Log Monitoring, Premium Hosting Care and the Reseller panel all have phases, and affiliate / referral now has one too |
#Still open after this phase
| # | Question |
|---|---|
| — | What happens when the referrer is not active? 18.6 requires an active referrer for the new user's credit Open question. Nothing says whether the sign-up simply earns nothing, or whether the new user is told. Showing a credit that never arrived would be worse than showing none |
| — | Is there any sign of the affiliate side inside Central? 18.3 says no dashboard, slabs or payouts, and 18.1's code is invisible Open question. So an affiliate signing in to Central sees nothing about their own programme — not even a link to Tolt. That may well be intended, but a pointer would stop support questions |