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

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 stats response reflects the current mode: it gains a top-level `reward_mode`
(`"referrer" | "affiliate"`) and an `affiliate` object (`allowed`, `min_payout`,
`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>
  The payout method, e.g. `paypal`.
</ParamField>

<ParamField body="paypal_email" type="string">
  The PayPal address to pay, when `method` is `paypal`.
</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": "paypal", "paypal_email": "jane@acme.com" }'
```

```json Response theme={null}
{ "partner_id": "pa1...", "payout_method": "paypal", "paypal_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.