Skip to main content
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 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:
On load the embed calls GET /api/v1/referrals/stats, which auto-enrolls the user (idempotent — same as POST /api/v1/referrals/enroll), so there is nothing else to wire up.

​
Attributes

​
string
required
A publishable key (pk_…) from Settings → Developers. Safe to expose in the browser.
​
string
required
The user’s id in your system — becomes their external_user_id.
​
string
The user’s email. Recommended — it’s used as the partner identity.
​
string
default:"free"
free or paid — decides which credit amount applies.
​
string
A CSS selector (e.g. #refer-earn) to render the dashboard into. If omitted, the dashboard renders where the script tag sits.
​
string
default:"light"
light or dark.
​
string
A hex brand color for the dashboard’s accent, e.g. #6366f1.
​
number
default:"30"
The analytics window in days, 7–90.
​
string
Only for custom deployments — the API origin to call. Defaults to the script’s own origin.

​
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 #):
  • 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:
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 #).
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. Only render the snippet to the already-authenticated user it belongs to; never let one user’s page embed another user’s id.

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

​
Set reward mode

POST /api/v1/referrals/reward-mode — switch a user between referrer and affiliate mode. Also available in the endpoint reference.
​
string
required
The user’s id in your system.
​
string
required
referrer or affiliate.
cURL
Response
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.
​
string
required
The user’s id in your system.
​
string
required
The payout method, e.g. paypal.
​
string
The PayPal address to pay, when method is paypal.
cURL
Response
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.

​
Under the hood

The dashboard is powered by a single endpoint you can also call yourself: GET /api/v1/referrals/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.