Concepts and glossary
The RefRef model in one page — Workspaces, Projects, Programs, participants, referrals, Events, benefit rules, Rewards, and partners.
This page defines the terms that the Console, the API, and these docs use. The terms are listed in the order in which you meet them when you set up RefRef.
Workspace
└── Project (a Live Project and its Sandbox Project)
├── Programs ── benefit rules ── reward terms
├── Participants ── enrollments ── referral codes and links
├── Events ── referrals ── Rewards
└── API keys, webhook endpoints, integrationsAccount structure
Workspace
A Workspace is your company's account in RefRef. It groups the people who use the Console and owns your Projects, your API keys, and your partner record. Each person who signs up gets a personal Workspace. A person can be a member of several Workspaces, and the Console sidebar switches between them.
Each member has one role in the Workspace: owner, admin, or member. Owners and admins change configuration. Members can read, but the Console does not show them the controls of admin-only operations, and the server refuses those operations. See Workspaces.
Project
A Project is one app or store that you connect to RefRef. It is the integration boundary: participants, Programs, Events, referrals, and Rewards belong to one Project and never cross to another one.
Each Project is a pair:
- The Live Project holds your real customers and real Rewards.
- The Sandbox Project is a separate twin for tests. It has its own ID, slug, signing secret, participants, Programs, and data. Its billing deliveries and payouts go through a simulated provider and move no money.
An API key belongs to one environment, Sandbox or Live, and reaches only the Projects of that environment. See Projects.
Program
A Program is a reward configuration inside a Project. Its kind is fixed when you create it:
referral: your customers refer through the Widget. A referrer brings a referee. Its benefit rules reward thereferrerrole, therefereerole, or both.affiliate: partners refer. They join through the join page or an invitation and use the Partner app. Its roles are those of a referral Program; areferrerrule pays cash or a custom reward.loyalty: rewards a participant for its own Events. Its benefit rules reward thesubjectrole, the participant of the Event.
A Project can have any number of Programs. Each Program also holds its brand settings, its landing page URL, and its delivery settings; a referral Program also holds its Widget settings, and an affiliate Program its partner settings and join page. See Programs.
People and companies
Participant
A participant is a person or a company in your product, as RefRef knows it. You name each participant with your own stable ID:
{ "kind": "individual", "externalId": "user_42" }for a person.{ "kind": "group", "externalId": "acct_7" }for a company, team, or account.
(individual, "42") and (group, "42") are two different participants. A trusted API call that names an unknown participant creates it, so there is no separate registration step. RefRef never matches participants by email and never merges them. It stores no group membership. See Participants.
Actor
An Event can name an optional actor: the individual who did something for a group participant. For example, Carol signs up her company: the participant is the company, and Carol is the actor. The actor never changes attribution.
Referrer and referee
Referrer and referee are roles on a referral, not kinds of participant. The referrer owns the referral code or link that the referee used. The referee is the participant of the Event that created the referral. A participant can be a referrer in one referral and a referee in another one. A participant can never refer itself.
Enrollment
An enrollment is the period during which a participant takes part in one Program. You enroll a participant from your backend or from the Console. A participant can be enrolled in several Programs at the same time, with at most one open enrollment in each Program. Ending an enrollment stops new referrer Rewards from that Program. A participant can enroll again later.
Partner
A partner is an outside party, such as an affiliate or an agency, that promotes your affiliate Program with its own RefRef login. A partner joins through an invitation that you send by email, or through an application that you approve. It then uses the Partner app to get its link and follow its referrals and Rewards. A referrer that did not join this way is not a partner. See Partners.
Referral evidence
Referral code and referral link
A participant owns one referral code in each referral Program. The code stays the same when the participant ends an enrollment and enrolls again. A referral link is a URL with the code, for example https://r.refref.ai/<code>; https://refref.ai/r/<code> also works. A vanity link adds a readable slug, unique in the Project, that points to the same code: https://r.refref.ai/<project-slug>/<slug>, or https://<your-domain>/<slug> on an active custom link domain.
A person can also type a code, for example at checkout. Your backend sends it on the Event as refCode.
Handle
A handle is RefRef's record of the referral clicks in one browser, before RefRef knows who the person is. The landing script gets the handle from RefRef after a click and keeps its ID in the first-party cookie refref_handle for 90 days. The handle ID is a random value, not a signed token.
Identification
An identification tells RefRef that a handle belongs to a participant. Your backend sends it once, at the identity moment: when the account or the company is created. Sign-in, email verification, and account linking never identify. Without an identification, a click never counts. See signup tracking.
Reference
A reference is a temporary key for a sign-up flow that can end on another device or a hosted page, such as a magic link. Your backend identifies the browser's handle to the reference when the flow starts, and resolves the reference to the participant when the account exists. A reference resolves once and expires after 24 hours by default.
Touch
A touch is one piece of referral evidence: a click on a referral link, or a code that the referee typed. RefRef chooses among the touches when it decides an Event.
Referral
A referral is the preserved relationship from a referrer to a referee in a Project, with the Program and the touch that created it. Each referee has at most one referral in a Project. The first Event of a qualifying type that has an eligible touch creates it. Later clicks do not replace it, and later purchases and renewals use it without a new click.
A click is eligible when it happened at most 90 days before the identification, and the referrer was enrolled in the Program at both times. A typed code that counts wins over every click. Otherwise the latest eligible click wins.
Events and Rewards
Event
An Event is one fact about one participant that your backend or an integration sends to RefRef. Its type is one of:
signup: built in. A participant has one signup.purchase: built in. A paid invoice or order, with its amounts.- A type that you define, which starts with
custom_, for examplecustom_demo_booked.
Every Event gets an attribution decision: attributed to a referral, or unattributed with a reason. See Events.
Qualifying event types
The qualifying event types of a Project are the types that can create a new referral. The default is signup and purchase. An Event of another type cannot create a referral, but it uses an existing referral, so a benefit rule can still reward it.
Subscription
A Subscription is a recurring purchase. Its start fixes its origin: attributed to a referral, or not. Its renewals keep that origin, also after 90 days and without a new click.
Benefit rule
A benefit rule says who earns what for which Event type in a Program:
- Event type: for example
signup,purchase, or acustom_type. - Beneficiary role:
referrerorrefereein a referral or affiliate Program,subjectin a loyalty Program. - Purpose:
primaryorbonus. Each Program, event type, and role has at most one primary rule. Bonus rules pay in addition to it. - Name: a label that you can change. Nothing else in a rule changes.
Reward terms
The reward terms are the amount and limits of a benefit rule. Each publication makes a new, immutable terms version that takes effect at once. An Event uses the version that was in effect when the Event occurred. A new version does not reset the limits that a participant already used.
The terms set the benefit kind:
| Benefit kind | What the beneficiary gets |
|---|---|
cash | Money, as a fixed amount or a percentage of a purchase. Not for the referee role. |
credit | Account credit in your product, as a fixed amount or a percentage of a purchase |
discount | A percentage discount |
custom | A quantity of one of your custom units, for example 500 MB of storage or 1 month of a plan |
The terms also set the duration (once, a fixed number of months, or lifetime) and an optional cap on the Rewards of one beneficiary. For a discount, the duration is how long the code lasts; a discount is earned once.
Custom unit
A custom unit is a thing that your product grants, with a stable key such as storage_mb and a name that people read, such as "MB of storage". Each Project has one list of units that all its Programs share.
Reward
A Reward is what a participant earned from one Event under one terms version. It is an accounting fact. It does not prove that money, credit, or a discount was delivered. See Rewards and delivery.
Delivery method
Each Reward has one fulfillment record, and its delivery method says who delivers the Reward:
| Method | Who delivers |
|---|---|
operator | Your product grants it, usually after a reward.earned webhook |
manual | A person on your team grants it or pays it, then records it |
billing_credit | RefRef adds account credit through your connected billing provider |
billing_discount | RefRef applies a discount through your connected billing provider |
billing_plan_upgrade | RefRef moves the subscription to a higher plan for free periods |
payout | RefRef pays the cash Reward to the beneficiary's PayPal address, in US dollars |
The Program's delivery settings choose the method for each benefit kind.
Reward void
An owner or admin can void a Reward, with a reason. A void is final: there is no reinstatement. It cancels a delivery that did not start. It does not recover money or a discount that was already delivered, and it does not give back the limit that the Reward used.
Integration terms
Widget
The Referral Widget is a panel that you embed in your product. It shows an enrolled participant its referral link and share buttons. Your backend signs a short-lived token for it. See Widget.
Webhook event
RefRef records an event for each new participant, referral, Event decision, Reward change, and payout outcome. It sends each one as a signed webhook and keeps all of them in a feed. See Webhooks.