Skip to main content

​
Referrals

The Referrals console at /marketing/referrals runs your member-get-member programs: you define the reward, each contact receives a unique share code, and the console tracks the funnel from visit to signup to paid-out reward. The marketing hub overview positions this console against Loyalty, Incentives, and Wallet Passes; the Referral programs guide walks the programmatic workflow; the concept page defines the model underneath. Referrals is a tenant-owned control. Programs, codes, visits, and conversions exist only in your workspace: nothing earns until you create and enable a program, and no payout moves until you approve it.

​
What you see on the page

The console has two views: the program list, and one detail view per program.

​
Program list

One card per program: The header’s Create program button opens the program form: the program name, the reward type, the referrer and referee rewards, the target URL new signups land on, and optional start and end dates.

​
Program detail

The detail view stacks three surfaces: Funnel stats. Three tiles across the top — Total referrers, Signups, Rewards paid — the spread of the program at a glance. Leaderboard. Top referrers in this program, one row per referrer with the columns Contact, Code, Visits, Signups, and Rewards paid. Each row carries a Copy action for the contact’s /r/<code> short link. The header adds Issue code, which hands a code to a specific contact, and Edit program, which reopens the form. Conversions. Recent referee signups, with the columns When, Referrer, Referee, and Status. A conversion whose reward is still pending shows a Pay action; the confirmation dialog names the referrer and the amount, and Pay reward approves the payout.

​
Who can read and who can act

The dashboard and the API gate the console at different layers: A signed-in member outside the dashboard roles does not see the console. An API key outside the write roles can read, and receives a 403 on writes. Checks like payout approval are money actions, so they sit behind the same guards rather than a separate one.

​
Worked examples

​
Approve a pending reward payout

  1. Open Referrals, then choose Open on the program.
  2. In Conversions, find the referee signup whose status is pending.
  3. Choose Pay on the row. The dialog names the referrer and the reward amount.
  4. Confirm with Pay reward. The row’s status updates, and the payout also posts to the Incentives ledger tagged to this program.

​
Hand a contact their share code

  1. On the program detail, choose Issue code and pick the contact.
  2. The console mints the code and shows the /r/<code> short link.
  3. Copy the link from the dialog or from the leaderboard row, and deliver it over any channel you already use. The link, not the channel, carries the attribution.

​
Read the funnel after a week

  1. The three tiles give the rates by eye: Signups per Total referrers, Rewards paid per Signups.
  2. In the leaderboard, a row with visits but no signups points at the landing page, not at the program; a row with signups but no paid rewards means payouts are waiting on your approval in Conversions.

​
API pairing

Everything above is reachable programmatically; the Referrals API reference is the contract for field lists. The console’s create-program dialog writes the same body as:
Issuing codes and approving payouts map to the code and conversion endpoints under the same reference. A 403 on a write is the role gate working: the key must belong to an owner, admin, or developer.

​
Tenant-owned controls

Nothing in this console is platform-mandated. Reward amounts, the target URL, program start and end dates, and every payout approval are values you set; the platform never creates, enables, or pays out on your behalf, and deleting a program removes its codes, visits, and conversions from your workspace.