> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Referrals console reference

> The /marketing/referrals console end to end: program cards and their fields, the funnel stat tiles, the leaderboard and conversions tables, the payout approval flow, the role gates on reads and writes, and the API calls behind each control.

# 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](/marketing/overview) positions this console against Loyalty, Incentives, and Wallet Passes; the [Referral programs guide](/guides/referral-programs) walks the programmatic workflow; the [concept page](/concepts/referral-program-model) 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:

| On the card | What it tells you |
| - | - |
| Name and status badge | **Active** while the program is enabled, **Inactive** once switched off |
| Reward line | The reward type — **Credit reward**, **Discount code**, or **Custom (webhook)** — and its value |
| **Open** | Drill into the program's funnel, leaderboard, and conversions |
| **Delete** | Remove the program together with its codes, visits, and conversions; the console asks for confirmation first |

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:

| Surface | Read | Write |
| - | - | - |
| Dashboard console (list, funnel, leaderboard, conversions) | Workspace roles **owner**, **admin**, or **billing** | The same roles: create, edit, and delete programs, issue codes, copy links, approve payouts |
| Referrals API | Any authenticated key or session | Program and code writes additionally require role **owner**, **admin**, or **developer** |

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](/marketing/incentives) 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](/api-reference/referrals) is the contract for field lists. The console's create-program dialog writes the same body as:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orbit.devotel.io/api/v1/referrals/programs \
    -H "X-API-Key: dv_live_sk_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Give 10 Get 10",
      "reward_type": "credit",
      "reward_value": "$10 credit",
      "referrer_reward": { "amount": 10, "currency": "USD" },
      "referee_reward": { "amount": 10, "currency": "USD" },
      "target_url": "https://yourbrand.example/signup"
    }'
  ```

  ```typescript Node.js theme={null}
  import { Orbit } from "@devotel-orbit/node";

  const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

  const { data: program } = await orbit.request<{ id: string }>(
    "POST",
    "/referrals/programs",
    {
      body: {
        name: "Give 10 Get 10",
        reward_type: "credit",
        reward_value: "$10 credit",
        referrer_reward: { amount: 10, currency: "USD" },
        referee_reward: { amount: 10, currency: "USD" },
        target_url: "https://yourbrand.example/signup",
      },
    },
  );

  console.log(program.id); // pass to /referrals/programs/:id/codes
  ```
</CodeGroup>

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.