Referrals

These endpoints drive product-led referrals: enroll each user as a referrer, tell TrackRev when a referred person signs up so the inviter earns their reward, and read a user’s referral stats for the dashboard embed. All accept a publishable (pk_) or secret (lk_) key, so they’re safe to call from the browser.

Enroll a referrer

curl -X POST "https://app.trackrev.io/api/v1/referrals/enroll" \
  -H "Authorization: Bearer <pk_ or lk_ key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "external_user_id": "USER_123",
    "tier": "paid"
  }'

POST /api/v1/referrals/enroll — enroll a user as a referrer and mint their referral link. Idempotent on (workspace, external_user_id).

string

required

The user’s email.

string

required

Your stable user id.

string

required

free or paid — sets the reward amount.

string

Target a specific programme; defaults to your most recent one.

string

The user’s name.

string

A device fingerprint, used for self-referral checks.

string

The user’s shareable referral URL.

string

The enrollment status (auto-approved for referrals).

{
  "partner_id": "pa1...",
  "program_id": "p1...",
  "referral_link": "https://acme.trackrev.io/user-123",
  "status": "approved"
}

curl -X POST "https://app.trackrev.io/api/v1/referrals/report-signup" \
  -H "Authorization: Bearer <pk_ or lk_ key>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_user_external_user_id": "USER_456",
    "email": "friend@example.com",
    "ref_code": "user-123"
  }'

POST /api/v1/referrals/report-signup — tell TrackRev that a referred user signed up, so the referrer earns their reward. Idempotent per new user.

string

required

The new user’s id.

string

The new user’s email.

string

The new user’s device fingerprint (for self-referral checks).

string

The referrer’s link slug — the primary way to resolve who referred them.

string

A visitor id — resolves the referrer from the most recent click if no ref_code.

string

Name the referrer explicitly.

The referrer is resolved in order: ref_code → _vid → referrer_external_user_id. TrackRev runs self-referral checks; blocked grants are recorded as revoked and no reward webhook fires.

boolean

Whether a referrer was found.

string

boolean

Whether the reward was blocked as a self-referral.

string | null

{ "matched": true, "program_id": "p1...", "partner_id": "pa1...", "blocked": false, "block_reason": null }

If no referrer matches, the response is { "matched": false } with a 200 status — a signup with no referrer isn’t an error.

Report a purchase

curl -X POST "https://app.trackrev.io/api/v1/referrals/report-purchase" \
  -H "Authorization: Bearer <lk_ secret key>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "USER_456",
    "order_id": "inv_9021",
    "amount": 49.99,
    "email": "friend@example.com"
  }'

POST /api/v1/referrals/report-purchase — tell TrackRev a user paid, so their referrer earns the purchase-side reward: a cash commission at the program’s affiliate terms when the referrer is in affiliate mode, the qualifying-sale credit on credit programs, and multi-tier fan-out where enabled. Only needed when your billing is not a connected provider — Stripe, Paddle Billing, Polar, Lemon Squeezy, Creem and Dodo Payments report purchases automatically through their webhooks and never need this call. Requires a secret key (this mints money). Idempotent per order_id: replays return the same order and never double-credit.

string

required

The paying user’s id in your system.

string

required

Your order / invoice / payment id — the idempotency key.

number

required

Purchase amount in major units (e.g. 49.99).

string

ISO code, default usd.

string

The buyer’s email.

boolean

true for a renewal — programs with first-sale-only terms skip it.

string

ISO timestamp of the purchase; defaults to now.

The referrer is resolved from the buyer’s reported signup (report-signup), so report signups first — a purchase by a user whose signup was never reported returns { "matched": false }.

boolean

Whether the buyer was referred.

boolean

Whether a commission or credit was written for this call.

number

TrackRev’s internal order id.

number

How many ledger rows were written (multi-tier writes one per level).

string

Present when the referral matched but nothing was written because of the plan: plan_has_no_commission_tracking (free plan — commission tracking needs a paid plan). No paid plan caps commission, so there is no other plan-related reason.

{ "matched": true, "credited": true, "order_id": 8123, "written": 1 }

Get referral stats

curl "https://app.trackrev.io/api/v1/referrals/stats?external_user_id=user_123&email=jane@acme.com&tier=paid&days=30" \
  -H "Authorization: Bearer <pk_ or lk_ key>"

GET /api/v1/referrals/stats — a user’s referral link, windowed stats, lifetime rewards and a daily series. This is the endpoint behind the dashboard embed. Auto-enrolls the user if they aren’t a referrer yet (idempotent — same as enroll).

string

required

The user’s id in your system.

string

The user’s email. Recommended — used as the partner identity.

string

default:"free"

free or paid — decides which credit amount applies.

number

default:"30"

The stats window in days, 7–90.

string

The enrollment status (auto-approved for referrals).

string

The user’s shareable referral URL.

number

The window the stats and series cover.

object

clicks, signups, purchases and conversion_rate over the selected window.

object

All-time rewards: cash (currency, pending, paid, total, in major currency units — e.g. dollars) and credits (per kind: earned, delivered, pending).

array

One entry per day in the window: day, clicks, signups, purchases.

string

How this user is currently rewarded: referrer (credits) or affiliate (cash commissions). See Set the reward mode.

object

Affiliate-mode details: allowed (whether the program offers the upgrade), min_payout (major currency units, same as lifetime.cash; the threshold of the campaign the user is paid under), payout_methods (the methods the program offers: any of paypal, payoneer, wise), payout_method (the saved choice, { method, email, paypal_email } with the address masked, or null), recent_commissions (date, type, amount, earnings, status) and payouts (date, amount, status).

{
  "partner_id": "pa1...",
  "program_id": "p1...",
  "status": "approved",
  "referral_link": "https://acme.trackrev.io/user-123",
  "days": 30,
  "stats": { "clicks": 214, "signups": 18, "purchases": 6, "conversion_rate": 0.028 },
  "lifetime": {
    "cash": { "currency": "usd", "pending": 45.5, "paid": 120, "total": 165.5 },
    "credits": [ { "kind": "ai_credits", "earned": 900, "delivered": 750, "pending": 150 } ]
  },
  "series": [ { "day": "2026-07-01", "clicks": 4, "signups": 1, "purchases": 0 } ],
  "reward_mode": "referrer",
  "affiliate": {
    "allowed": true,
    "min_payout": 50,
    "payout_methods": ["paypal", "payoneer"],
    "payout_method": null,
    "recent_commissions": [],
    "payouts": []
  }
}

Errors use the standard envelope — e.g. 401 unauthorized for a missing or invalid key, 400 bad_request for invalid parameters such as a missing external_user_id.

Set the reward mode

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"
  }'

POST /api/v1/referrals/reward-mode — switch a user between referrer mode (earn credits) and affiliate mode (earn cash commissions at the program’s commission rate). Powers the toggle in the dashboard embed. The switch affects future conversions only — credits already earned are kept — and is reversible.

string

required

The user’s id in your system.

string

required

referrer or affiliate.

string

The mode now in effect.

{ "partner_id": "pa1...", "program_id": "p1...", "reward_mode": "affiliate" }

Errors use the standard envelope — 403 forbidden when the program doesn’t allow the affiliate upgrade, 400 bad_request for an invalid mode or missing external_user_id.

Set the payout method

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"
  }'

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). The address is stored on the user’s enrollment in your program: it never changes how other merchants pay the same affiliate, and it takes precedence over the address the affiliate set in their own partner-portal settings when you export payouts.

string

required

The user’s id in your system.

string

required

paypal, payoneer or wise — and one your program offers (400 method_not_offered otherwise). Bank transfers aren’t available yet.

string

required

The email on the user’s account for that method. paypal_email is accepted as an alias.

string

Only when method is paypal.

{ "partner_id": "pa1...", "payout_method": "payoneer", "email": "jane@acme.com" }

API Reference

Endpoints

Events & embeds

Enroll a referrer

Report a purchase

Get referral stats

Set the reward mode

Set the payout method

​Enroll a referrer

​Report a signup

​Report a purchase

​Get referral stats

​Set the reward mode

​Set the payout method

Enroll a referrer

Report a signup

Report a purchase

Get referral stats

Set the reward mode

Set the payout method