Skip to content

Referral API

The referral system lets users share referral links, attribute signups, and earn commission on referred users' usage. Authenticated endpoints require Authorization: Bearer <token>. Admin endpoints require an admin account.

User endpoints

  • POST /referral/link — Get or create your referral link. Returns { referralCode, referralLink }.
  • GET /referral/stats — Clicks, registrations, active referrals (30-day), total commission.
  • GET /referral/users — Paginated list of referred users (signup date, usage, commission earned, status).
  • GET /referral/commissions — Paginated commission history (optional from, to query).
  • POST /referral/click — Record a click (body: { referralCode }). Rate-limited; no auth required.

Admin endpoints

  • GET /admin/referral-settings — Current default commission percent.
  • PATCH /admin/referral-settings — Update default commission (body: { defaultCommissionPercent }).
  • GET /admin/referrals — Top referrers and total payout (optional search, page, limit).
  • GET /admin/referrals/:referrerId/users — Referred users for a referrer (optional page, limit).

Registration

POST /auth/register accepts an optional referralCode in the body. If valid, the new user is linked to the referrer and a Referral row is created. Self-referral and duplicate attribution are rejected.

Full request/response shapes and examples are in the spec: specs/006-referral-system/contracts/referral-api.md.

General guides

New to the product? Start with Getting started.