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

# Dashboard embed

> Embed a full Refer & Earn dashboard in your app — referral link, clicks, signups, purchases, conversion rate and rewards.

The dashboard embed renders a complete referral dashboard inside your product: the signed-in
user's referral link, their clicks, signups, purchases and conversion rate over a selectable
window, and the credits or cash they've earned. Where the [referral
widget](/developers/referral-widget) is a lightweight share card, the embed is the full analytics
view — an Affonso-style "Refer & Earn" page you don't have to build.

## Embed it

Paste the loader script inside your authenticated app, with a **publishable** key. It injects an
auto-resizing iframe:

```html theme={null}
<script async src="https://app.trackrev.io/embed.js"
  data-key="pk_live_xxxxxxxx"
  data-user-id="user_123"
  data-user-email="jane@acme.com"
  data-user-tier="paid"
  data-mount="#refer-earn"></script>
```

On load the embed calls [`GET /api/v1/referrals/stats`](/developers/endpoints/referrals#get-referral-stats),
which auto-enrolls the user (idempotent — same as
[`POST /api/v1/referrals/enroll`](/developers/endpoints/referrals#enroll-a-referrer)), so there is
nothing else to wire up.

## Attributes

<ParamField path="data-key" type="string" required>
  A publishable key (`pk_…`) from **Settings → Developers**. Safe to expose in the browser.
</ParamField>

<ParamField path="data-user-id" type="string" required>
  The user's id in **your** system — becomes their `external_user_id`.
</ParamField>

<ParamField path="data-user-email" type="string">
  The user's email. Recommended — it's used as the partner identity.
</ParamField>

<ParamField path="data-user-tier" type="string" default="free">
  `free` or `paid` — decides which credit amount applies.
</ParamField>

<ParamField path="data-mount" type="string">
  A CSS selector (e.g. `#refer-earn`) to render the dashboard into. If omitted, the dashboard
  renders where the script tag sits.
</ParamField>

<ParamField path="data-theme" type="string" default="light">
  `light` or `dark`.
</ParamField>

<ParamField path="data-accent" type="string">
  A hex brand color for the dashboard's accent, e.g. `#6366f1`.
</ParamField>

<ParamField path="data-days" type="number" default="30">
  The analytics window in days, `7`–`90`.
</ParamField>

<ParamField path="data-api-base" type="string">
  Only for custom deployments — the API origin to call. Defaults to the script's own origin.
</ParamField>

## Direct iframe

Prefer not to load a script? Point an iframe straight at the embed page and pass the same values
as query parameters (`accent` without the `#`):

```html theme={null}
<iframe
  src="https://app.trackrev.io/embed/referrals?key=pk_live_xxx&uid=user_123&email=jane%40acme.com&tier=paid&theme=light&accent=6366f1&days=30"
  style="width: 100%; border: 0;"
></iframe>
```

* `key` — the publishable key (required).
* `uid` — the user's id in your system (required).
* `email` — the user's email (recommended).
* `tier` — `free` or `paid` (default `free`).
* `theme` — `light` or `dark` (default `light`).
* `accent` — hex color **without** the `#`, e.g. `6366f1`.
* `days` — analytics window, 7–90 (default 30).

### Auto-resizing

The iframe posts its content height to the parent window so you can size it without scrollbars:

```json theme={null}
{ "type": "trackrev:embed:height", "height": 812 }
```

The `embed.js` loader listens for these messages and resizes the iframe automatically. If you use
the direct iframe, add a small `message` listener yourself and set the iframe's height from
`event.data.height` when `event.data.type === "trackrev:embed:height"`.

## Theming

Use `data-theme` (`light` | `dark`) to match your app's mode and `data-accent` to apply your brand
color to buttons, links and highlights. With the direct iframe, the same options are the `theme`
and `accent` query params (accent without the `#`).

<Warning>
  The end-user identity (`data-user-id`, `data-user-email`, `data-user-tier`) is **self-asserted**
  and trusted under your API key — the same trust model as the [referral
  widget](/developers/referral-widget). Only render the snippet to the already-authenticated user
  it belongs to; never let one user's page embed another user's id.
</Warning>

## Affiliate upgrade

The embed can offer end-users a choice of how they're rewarded:

* **Referrer** (default) — earn credits, exactly as today.
* **Affiliate** — earn direct cash commissions at the program's commission rate, with payout
  access, without ever leaving your app. (Partners who join via the public join page are
  affiliates only — this toggle is how your own users get there in-product.)

The toggle appears in the dashboard only when **both** are true:

1. The merchant enabled **Allow customers to become affiliates** in the program settings
   (`programs.allow_affiliate_upgrade`), and
2. the program is **credit-based** (`credit_enabled`). Cash-based programs already pay cash —
   no toggle is shown.

Affiliate mode pays the program's `commission_type` / `commission_rate` — merchants set this
commission alongside the toggle in the program settings.

<Warning>
  Cash commissions are written when TrackRev learns about the **purchase**. If your billing runs
  on a connected provider (Stripe, Paddle, Polar, Lemon Squeezy), that happens automatically
  through its webhooks. If you bill any other way, your backend must call
  [`POST /api/v1/referrals/report-purchase`](/developers/endpoints/referrals#report-a-purchase)
  when a user pays — without it, affiliate-mode referrers never earn and the embed's Purchases
  stays at 0. Report signups with
  [`report-signup`](/developers/endpoints/referrals#report-a-signup) first: purchases are matched
  to referrers through the reported signup.
</Warning>

Switching affects **future conversions only** — credits already earned are kept — and is fully
reversible. While in affiliate mode, the embed swaps in an embedded portal view: cash balance
(pending / eligible / paid), recent commissions, payout-method setup, payout history, and the
program's minimum payout threshold. The payout form offers exactly the methods you switched on in
the program's payment settings (PayPal, Payoneer or Wise) and labels the field for the one the
user picks, e.g. "Payoneer email for payouts".

The stats response reflects the current mode: it gains a top-level `reward_mode`
(`"referrer" | "affiliate"`) and an `affiliate` object (`allowed`, `min_payout`,
`payout_methods`, `payout_method`, `recent_commissions`, `payouts`) — see
[`GET /api/v1/referrals/stats`](/developers/endpoints/referrals#get-referral-stats).

### Set reward mode

`POST /api/v1/referrals/reward-mode` — switch a user between referrer and affiliate mode. Also
available in the [endpoint reference](/developers/endpoints/referrals#set-the-reward-mode).

<ParamField body="external_user_id" type="string" required>
  The user's id in your system.
</ParamField>

<ParamField body="mode" type="string" required>
  `referrer` or `affiliate`.
</ParamField>

```bash cURL theme={null}
curl -X POST "https://app.trackrev.io/api/v1/referrals/reward-mode" \
  -H "Authorization: Bearer <pk_ or lk_ key>" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "user_123", "mode": "affiliate" }'
```

```json Response theme={null}
{ "partner_id": "pa1...", "program_id": "p1...", "reward_mode": "affiliate" }
```

Returns `403 forbidden` when the program doesn't allow the upgrade, `400 bad_request` for an
invalid mode or missing id.

### Set payout method

`POST /api/v1/referrals/payout-method` — save where an affiliate-mode user gets paid. Only
accepted while the enrollment is in affiliate mode (`403 forbidden` otherwise). Also in the
[endpoint reference](/developers/endpoints/referrals#set-the-payout-method).

<ParamField body="external_user_id" type="string" required>
  The user's id in your system.
</ParamField>

<ParamField body="method" type="string" required>
  `paypal`, `payoneer` or `wise` — and one your program offers. Bank transfers (wire, ACH) aren't
  available yet. A method the program doesn't offer returns `400 method_not_offered`.
</ParamField>

<ParamField body="email" type="string" required>
  The email on the user's account for that method. `paypal_email` is accepted as an alias.
</ParamField>

```bash cURL theme={null}
curl -X POST "https://app.trackrev.io/api/v1/referrals/payout-method" \
  -H "Authorization: Bearer <pk_ or lk_ key>" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "user_123", "method": "payoneer", "email": "jane@acme.com" }'
```

```json Response theme={null}
{ "partner_id": "pa1...", "payout_method": "payoneer", "email": "jane@acme.com" }
```

<Warning>
  Payout-email changes ride the same trust model as the rest of the embed: the identity is
  self-asserted under your API key. Only render the dashboard (and thus the payout form) to the
  authenticated user it belongs to.
</Warning>

## Under the hood

The dashboard is powered by a single endpoint you can also call yourself:
[`GET /api/v1/referrals/stats`](/developers/endpoints/referrals#get-referral-stats) — windowed
stats, lifetime rewards and a daily series, with auto-enrollment built in. Use it directly if you
want the numbers in your own UI.


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