> ## 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.

# Set up a referral campaign from the dashboard, step by step

> Author a referral program in the dashboard — pick the reward, issue per-contact links, watch visits, signups, and payouts — and run the whole campaign without touching the API.

# Set up a referral campaign from the dashboard

This guide walks a referral campaign end to end using only the dashboard: creating the program, choosing the reward, issuing a unique link per referrer, tracking the funnel on the program page, and approving payouts. The [Referral programs](/guides/referral-programs) guide covers the same surface through the API instead — pick whichever flow you run.

## 1. Where referral programs live

Referral programs live under **Outbound → Referrals** at `/marketing/referrals`. The canonical module moved into the marketing namespace; an old `/outbound/referrals` bookmark redirects to the canonical list, and `/outbound/referrals/[id]` deep links redirect to the matching program page, so either entry lands in the same place.

The page is role-gated to **owner**, **admin**, and **billing** roles. Program configuration exposes reward amounts and payout rules, so restricted roles do not see the screen, and read-only roles cannot open the create dialog or the pay controls.

## 2. Author the campaign

On the list page, click **Create program**. The dialog asks for the same configuration the API accepts, broken into these fields:

| Field                                | What it does                                                                                                                                                                                                               |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                             | Display name for the program card and detail page.                                                                                                                                                                         |
| **Reward type**                      | `Credit` pays the reward into your wallet balance, `Discount code` mints a redeemable code through the incentives engine on payout, `Custom (webhook)` records a structured payout you fulfill yourself.                   |
| **Reward value (label)**             | Human-readable label rendered on the program page and in the pay confirmation, e.g. "20% off next month".                                                                                                                  |
| **Referrer reward / referee reward** | Amount per side. Set both for a two-sided offer; leave the referee side empty for referrer-only. Amounts are minor units for `Credit`, percentage points for `Discount code`.                                              |
| **Fulfillment provider**             | For non-credit rewards, the eligible incentive providers for the chosen reward type are listed; leave it on auto to let the engine pick its default. The picker is hidden for `Credit`, which goes straight to the ledger. |
| **Landing URL**                      | Where referred visitors land after they click a referral link. Must be an absolute `https` URL; blank falls back to the app root.                                                                                          |
| **Enabled**                          | Defaults to on. Leave it off to stage a program before launch — it stays visible in the list and can be switched on with Edit.                                                                                             |

After the program exists, open it from the list and use **Edit** to update any field. **Delete** removes the program together with its issued codes and recorded conversions — it is a cascade, so prefer toggling **Enabled** off for a dormant program you might relaunch.

## 3. Issue per-channel and per-contact links

Every referrer gets their own code rather than one shared link:

1. Open the program and click **Issue code**.
2. Search your contacts and pick the person who will share the link.
3. The dialog mints the code (or returns the existing one for that contact — re-issuing is idempotent) and shows the public short link with a copy button.

The link points at the public redirect, for example `https://api.orbit.devotel.io/r/AbCdEf23`. Because each contact carries a separate code, per-channel offers work by issuing codes to different cohorts — your SMS push list, your email list, an ambassador group — and reading their funnel numbers separately on the leaderboard. A channel that underperforms shows up as its own low-visit row, not as noise blended into one shared link.

Distribute the links however you send: drop the URL into an SMS or email campaign, or hand it to the contact from their Contact 360 record. The usual send gates — quiet hours, suppression lists, frequency caps — still fire before any message carrying a link goes out.

## 4. Read the campaign's counters

Open a program from the list. The detail page answers three questions:

**Stat cards.** Total referrers, Signups, and rewards paid, aggregated across every issued code in the program — the whole program, not just the visible leaderboard entries.

**Leaderboard.** Each referrer's code with its own **Visits**, **Signups**, and **Rewards paid** counters, ranked by conversions, with resolved contact names and a **Copy** button for the share link. This is where you compare the cohorts from section 3.

**Conversions.** Every recorded signup with when it happened, referrer, referee, and its reward status — `pending`, `paid`, or `rejected` — plus the reject reason when the built-in fraud guards declined it.

## 5. Approve payouts

Payouts are an operator decision: a recorded conversion sits at `pending` until you approve it.

1. In the **Conversions** table, find a pending row.
2. Click **Pay reward** — the confirmation states the reward and the recipient before anything moves.
3. Confirm. The conversion flips to **paid** and the reward fulfills:

   * `Credit` — the configured amount is applied per side.
   * `Discount code` — a redeemable code is minted and delivered through the incentives engine.
   * `Custom (webhook)` — a tracked payout record is created for your own fulfillment process.

Every payout is audit-logged with the referrer, referee, and reward summary. Rejected conversions are never payable — the reject reason stays on the row so a suspicious burst is visible instead of silently dropped.

## 6. Worked example: a send-to-redeem ladder

"Acme Wellness" runs a member referral promotion where the reward grows with engagement:

1. **Create the program.** Reward type `Discount code`, label "20% off next month", referrer amount 20, referee amount 10, fulfillment provider on auto, landing URL `https://acme.example/join`, enabled from day one.
2. **Issue codes per channel.** Open the program, click **Issue code**, and mint codes for three cohorts separately: the members you contact via SMS push, the email newsletter list, and the front-desk ambassador group. Each member picks up their personal link from their cohort send.
3. **Watch the ladder.** The leaderboard separates the channels: SMS push shows 480 visits and 63 signups, email 310 visits and 21 signups, ambassadors 190 visits and 40 signups. The numbers say the SMS cohort wins on volume but the ambassadors convert per visit — so next quarter's promotion leans into the personal-share motion.
4. **Approve weekly.** A weekly ops pass filters the conversions table to `pending` rows, sanity-checks that rejection reasons are sparse, confirms the payout dialog, and clicks **Pay reward**. Each referee walks away with a minted 10% code; each referrer collects 20% off their next month.

## 7. Limits and when attribution is not possible

* **Anti-abuse guards run on every conversion.** Visit and signup from the same IP, or a referrer and referee created within minutes of each other, are recorded as `rejected` with a structured reason rather than counted toward a payout. A high rejection rate on a program is a signal of link scraping, not random noise.
* **The public redirect is rate-limited per client IP**, so a circulated link picked up by a scraper farm does not inflate visit counts.
* **Role gating is always on.** Only owner, admin, and billing roles see the referrals surface; the penalty for an off-role user is that the page does not exist for them.
* **Attribution needs the link to be clicked.** If a new contact is created without the referral code context — a direct signup on your site with no click-through, a import, an API integration that never passes the parameter — there is no referrer to credit, and no retroactive correction is offered. Issue links per channel whenever possible so a missing click does not show up as "the campaign underperformed."

## 8. Related reading

* [Referral programs](/guides/referral-programs) — the same workflow driven through the API for automated cohort management.
* [Referral program model](/concepts/referral-program-model) — the concepts behind programs, codes, and conversions.
* [Incentives ledger](/guides/incentives-ledger) — where non-credit rewards and their fulfillment providers are configured.
* [Referrals API reference](/api-reference/referrals) — per-endpoint request and response contracts.