# Referrals (/docs/concepts/referrals) A referral program rewards members for bringing friends. You decide when an invited friend counts and what the inviter, the friend, or both earn. For example: * **"Invite a friend, you both get 100 XP"** once the friend signs up. * **A friend counts only after their first quest**, so empty sign-ups earn nothing. * **A bonus at 5 and 10 friends**, on top of the per-friend reward. * **10% of the XP your friends earn** for their first month, paid to you as extra points. Each member has at most one inviter in a project and environment. ```mermaid flowchart LR I["Invitation code"] --> A["Attribution"] A --> Q["Qualification"] Q --> F["Fixed rewards and milestones"] Q --> B["Percentage bonuses"] ``` ## What members see [#what-members-see] A member shares their invitation code or link. The friend opens it, signs in, and accepts the invitation; Domino records who invited them. The inviter can see how many friends they've invited, how many qualified, and which milestones they've reached. Rewards follow once a friend qualifies. Where [member profiles](/docs/build/profiles#compose-a-profile-page) are visible, a signed-in member can see another member's progress in a program: how many friends they invited, how many qualified, and which milestones they reached. It never shows referral codes or accounts. ## Attribution and qualification [#attribution-and-qualification] Inviting and qualifying are two steps. Your app carries the invitation code through sign-in and accepts it; Domino checks it and records the inviter. The friend then **qualifies** under the program's rule: | Qualification | The invited friend qualifies when… | | ------------- | ------------------------------------------------------------- | | Signup | They sign up and accept the invitation. | | Named quest | They complete the named quest. | | External | Your server records that they qualified, after its own check. | One quest completion can do several jobs at once: pay the friend points, unlock their next quest, and qualify the referral. The quest checks the activity; the referral program rewards the invitation. ## Rewards and corrections [#rewards-and-corrections] | Reward | What it grants | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Fixed rewards | Points or tier rewards for the inviter, the invited friend, or both. Badges and group memberships come from quests. | | Milestones | Rewards for reaching a number of distinct qualified friends. | | Percentage bonuses | A share of the points the friend earns in one ledger, optionally only from the quests you choose, and optionally for a set number of days or up to a cap. [Engagement](/docs/concepts/ugc#engagement-credits-growth) payouts of a covered quest count too. The inviter's bonus is extra: it never reduces the friend's own award. | Bonuses don't stack on bonuses. Fixed referral rewards and bonus payouts don't trigger further bonuses, and points from a [leaderboard prize](/docs/concepts/leaderboards#prize-settlements) earn none. Where [member profiles](/docs/build/profiles#compose-a-profile-page) are visible, a signed-in member can see another member's progress in one program: how many friends they invited, how many qualified, and which milestones they reached. It never shows referral codes or accounts. > [!DEV] > A quest's `evaluate` reads the same progress for the member it evaluates, as inviter, with [`ctx.member.referrals(program)`](/docs/reference/verification#evaluator-readers-null-errors-and-pinning). Things can change after a reward is paid: * **Corrections** can withdraw a friend's qualification and take back the rewards it paid. * **Revoking the qualifying completion** moves a named-quest qualification to another accepted completion of that quest, or unqualifies the friend and reverses the inviter's reward. See [revoke a completion](/docs/concepts/quests#revoke-a-completion). * **Pausing a member's referral earnings** keeps who invited whom and stops future payouts. * **Resuming** doesn't pay what was missed while paused. A [member import](/docs/use/imports#what-an-import-records) can bring over who invited whom from another platform, with the programs each friend already qualified in. Imported referrals pay no fixed reward, milestone or bonus at import; they count toward the inviter's qualified friends, and the friend's later points pay the bonus. > [!IMPORTANT] Referral earnings can change > Because of corrections and pauses, don't present referral earnings as final. > [!DEV] From the CLI > `domino referral-programs list` lists published programs, `domino referral-relationships list` pages relationships with their qualifications and the rewards waiting for review, and `domino referral-relationships history MEMBER` pages one member's referral points. `domino referral-programs qualify PROGRAM MEMBER --reason "…"` qualifies a member after an external check (`--disqualify` withdraws it), and `domino referral-rewards resolve ENTITLEMENT --reason "…"` marks a held reward reconciled. Changes need `publish`. > [!DEV] Notify your backend > When a referral qualification becomes active, the `referral.qualified` [webhook event](/docs/reference/webhooks) can notify your backend. It identifies the program, member, inviter, and any associated completion. ## Where next [#where-next] - [Publish a referral program](/docs/build/referrals) — Configuration, acceptance, testing, and corrections. - [Compose a campaign](/docs/composition) — Connect a program to quests and a leaderboard. ## Qualification with counters [#qualification-with-counters] A friend can be required to do several things before they count, such as three verified actions, without a separate referral counter. Use a quest that completes after three actions, and name it as the program's qualifying quest. Only that quest's awarded completion qualifies the referral. Rejected actions, unfinished counts and achievements a budget refused don't. > [!DEV] > Define a quest with `completion: progress({ distinct, goal: count(3) })`, then pass its typed handle to `questCompleted(qualificationQuest)` in `defineReferral`. The `qualified-referrals` snippet connects a custom activity tracker, a lifetime qualification quest and inviter/invitee rewards. Install it into a project that already has the SDK and CLI, then follow its `docs/snippets/qualified-referrals.md` to register the tracker, program and ledger: ```sh pnpm dlx shadcn@4.21.0 add https://snippets.domino.run/r/qualified-referrals.json ``` The snippet also includes a continuous Discord membership alternative: a manual claim checks the current server `joinedAt`, accepts after seven days, and rejects early claims with a not-yet-eligible reason. Leaving and rejoining starts a new interval. The member submits again later to capture fresh evidence; this example does not run a seven-day defer loop. Continuous server membership does not establish continuous role possession or screening status throughout the interval. ## Archive a referral program [#archive-a-referral-program] Archive a program with **Archive referral** on its card in **Referrals**, or in **Settings → Resources**, when it should stop qualifying new referrals and paying bonuses. Its relationships, past rewards and history stay readable, and corrections can still reverse earlier rewards. Members see the program as disabled. Unarchive it to start qualifying and paying again; archiving never erases accepted invitations. See [resource lifecycle](/docs/concepts/quests#resource-lifecycle). ## Pause a member's referral earnings [#pause-a-members-referral-earnings] Pause one member's referral earnings, with a reason, when you need to look into them. Their invitations stay; new payouts stop until you resume. > [!DEV] > Use `management.referrals.pause(member, { reason })` or `domino referral-relationships pause MEMBER --reason TEXT` to suspend the relationship. Use `resume` with a reason to restore it. These commands retain the existing `publish` permission and audited operator history. `referrals.suspend({ suspended })` remains a deprecated compatibility method.