'''Referrals are ungated and pay nothing.''' Before working a referral ticket, hold both halves of that in mind: there is no entitlement to check, and there is no balance, credit or payment to adjust. The only thing a referral produces is a badge.
== The four questions that arrive ==
=== "I invited five people and it says one" ===
'''By far the commonest, and almost never a bug.''' A referral counts only once the invitee has confirmed their email address AND finished onboarding. Somebody who signed up and stopped partway shows on the member's screen as ''still setting up'' and does not count.
Check it without touching anybody's health data:
SELECT status, rejection_reason, created_at, qualified_at FROM referrals WHERE referrer_user_id = ORDER BY created_at DESC;
`pending` rows are people mid-setup. That is the answer, and it is not something support can complete for them.
=== "My code was refused" ===
The refusal always carries a reason. The five the member can actually hit:
* '''That is your own invite code.''' Self-referral. * '''An invite code has already been applied to this account.''' One per account, forever. * '''That code was created after your account.''' The code did not exist when they signed up. * '''Invite codes can be added within the first week of a new account.''' Outside the seven-day window. * '''We could not apply that code to this account.''' The fraud check. Deliberately vague, and explained below.
=== "It just says it couldn't be applied" ===
That is the `same_origin` rule: two accounts arriving from the same connection in a short window, or a burst of sign-ups against one code. '''The wording is vague on purpose''' and must stay that way, because a message naming the rule tells somebody exactly what to change.
Two things worth knowing before escalating one of these:
* '''A household is a false positive we accept.''' Two people in one home genuinely share an address. If the member's account is otherwise ordinary, escalate rather than arguing. * '''Testing on one device trips it.''' Anybody trying both sides of a referral from one laptop or one phone will hit this, and it is not a defect.
=== "What do I actually get?" ===
'''A badge, at nine milestones''': 1, 5, 10, 20, 40, 50, 100, 250 and 500 friends. Nothing else. Never offer, hint at, or promise Premium time, a credit, a discount, a refund or a prize in a referral ticket, and never suggest a review or a follow in exchange for anything.
== What support must not do ==
* '''Do not tell a member who used their code.''' The system deliberately does not surface it, and neither should we. Confirming that a particular person used a particular code is a disclosure about that person. * '''Do not tell a referee who owns a code.''' Same rule from the other side. * '''Do not hand-insert a `referrals` row to "fix" a count.''' It bypasses every check, and the unique index on `referee_user_id` means a mistake is not simply undoable.
== Escalate when ==
* A member reports a count that moved '''down'''. * A badge appeared and then vanished. * `GET /api/v1/referrals/me` returns anything other than 200 for a signed-in member. * An ordinary-looking member hits `same_origin` and has no plausible shared connection.
Attach the tenant access log line for the request. It gives the method, path, status and the app build from the User-Agent, which separates a decode bug from a gate.
== See also ==
* [[handling-health-permission-tickets|Handling health permission tickets]]
'''Referrals are ungated and pay nothing.''' Before working a referral ticket, hold both halves of that in mind: there is no entitlement to check, and there is no balance, credit or payment to adjust. The only thing a referral produces is a badge. == The four questions that arrive == === "I invited five people and it says one" === '''By far the commonest, and almost never a bug.''' A referral counts only once the invitee has confirmed their email address AND finished onboarding. Somebody who signed up and stopped partway shows on the member's screen as ''still setting up'' and does not count. Check it without touching anybody's health data: <pre> SELECT status, rejection_reason, created_at, qualified_at FROM referrals WHERE referrer_user_id = <id> ORDER BY created_at DESC; </pre> `pending` rows are people mid-setup. That is the answer, and it is not something support can complete for them. === "My code was refused" === The refusal always carries a reason. The five the member can actually hit: * '''That is your own invite code.''' Self-referral. * '''An invite code has already been applied to this account.''' One per account, forever. * '''That code was created after your account.''' The code did not exist when they signed up. * '''Invite codes can be added within the first week of a new account.''' Outside the seven-day window. * '''We could not apply that code to this account.''' The fraud check. Deliberately vague, and explained below. === "It just says it couldn't be applied" === That is the `same_origin` rule: two accounts arriving from the same connection in a short window, or a burst of sign-ups against one code. '''The wording is vague on purpose''' and must stay that way, because a message naming the rule tells somebody exactly what to change. Two things worth knowing before escalating one of these: * '''A household is a false positive we accept.''' Two people in one home genuinely share an address. If the member's account is otherwise ordinary, escalate rather than arguing. * '''Testing on one device trips it.''' Anybody trying both sides of a referral from one laptop or one phone will hit this, and it is not a defect. === "What do I actually get?" === '''A badge, at nine milestones''': 1, 5, 10, 20, 40, 50, 100, 250 and 500 friends. Nothing else. Never offer, hint at, or promise Premium time, a credit, a discount, a refund or a prize in a referral ticket, and never suggest a review or a follow in exchange for anything. == What support must not do == * '''Do not tell a member who used their code.''' The system deliberately does not surface it, and neither should we. Confirming that a particular person used a particular code is a disclosure about that person. * '''Do not tell a referee who owns a code.''' Same rule from the other side. * '''Do not hand-insert a `referrals` row to "fix" a count.''' It bypasses every check, and the unique index on `referee_user_id` means a mistake is not simply undoable. == Escalate when == * A member reports a count that moved '''down'''. * A badge appeared and then vanished. * `GET /api/v1/referrals/me` returns anything other than 200 for a signed-in member. * An ordinary-looking member hits `same_origin` and has no plausible shared connection. Attach the tenant access log line for the request. It gives the method, path, status and the app build from the User-Agent, which separates a decode bug from a gate. == See also == * [[handling-health-permission-tickets|Handling health permission tickets]]
