Referral API — FonProxy Referral Program, Codes & Stats

Last updated: October 15, 2026

For authentication and common headers, see API General.

Overview

Get Referral Info Auth required

GET /referral

Returns the user's referral code, percentages, and stats. Auto-creates a referral code on first access.

Response

{
  "id": "xK9mR2pL1w",
  "code": "a3f8c2d1",
  "incomePercentage": 5,
  "salePercentage": 0,
  "clicks": 142,
  "registrations": 23,
  "totalIncome": 12.50,
  "pendingIncome": 3.75
}

Name	Type	Description
`id`	`string`	Referral ID
`code`	`string`	Editable referral code (used in referral link)
`incomePercentage`	`number`	Percentage the referrer earns from each referred top-up
`salePercentage`	`number`	Discount percentage for referred users (future)
`clicks`	`number`	Total visitors who came via this referral
`registrations`	`number`	Total users who registered via this referral
`totalIncome`	`number`	Total completed referral income (USD)
`pendingIncome`	`number`	Pending referral income not yet credited (USD)

List Referred People Auth required

GET /referral/people

Returns the newest people who signed up through the user's link, with the middle of each address hidden.

Query Parameters

Name	Type	Description	Required
`limit`	`number`	How many people to return, newest first (default 5, max 20)	No

Response

{
  "total": 23,
  "people": [
    {
      "signedUpAt": "2026-04-08T11:20:00.000Z",
      "account": "j•••@gmail.com",
      "topups": 2,
      "spentUsd": 40,
      "earnedUsd": 2,
      "status": "paid"
    }
  ]
}

Name	Type	Description
`total`	`number`	Everyone who registered via this referral, not only the returned page
`signedUpAt`	`string`	Registration time (ISO 8601)
`account`	`string`	Masked email: first character, `•••`, then the domain
`topups`	`number`	Top-ups of this person that produced referral income
`spentUsd`	`number`	Sum of those top-ups (USD)
`earnedUsd`	`number`	Referral income earned from them (USD)
`status`	`string`	`paid` (all income credited), `pending` (some income not yet credited), `none` (no top-up yet)

Code

Update Referral Code Auth required

PATCH /referral/code

Update the referral code. Must be 3–30 characters, alphanumeric + underscore + hyphen.

Request Body

Name	Type	Description	Required
`code`	`string`	New referral code	Yes

Response

{ "code": "john_doe", "message": "referral.code_updated" }

Errors:

{ "message": "referral.code_invalid" }
{ "message": "referral.code_taken" }

Analytics

Referral Graph Auth required

GET /referral/graph

Returns time-series chart data for clicks, registrations, and income.

Query Parameters

Name	Type	Description	Required
`from`	`string`	ISO date start. Default 30 days ago	No
`to`	`string`	ISO date end. Default now	No
`granularity`	`string`	`hour`, `day`, `week`, `month`. Default auto	No

Response

{
  "graph": "referral",
  "granularity": "day",
  "from": "2026-02-23T00:00:00.000Z",
  "to": "2026-03-25T00:00:00.000Z",
  "series": [
    {
      "key": "clicks",
      "label": "Clicks",
      "color": "#3B82F6",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 15 },
        ...
      ]
    },
    {
      "key": "registrations",
      "label": "Registrations",
      "color": "#22C55E",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 3 },
        ...
      ]
    },
    {
      "key": "income",
      "label": "Income (USD)",
      "color": "#151515",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 2.50 },
        ...
      ]
    }
  ],
  "meta": { "currency": "USD" }
}

How Referrals Work

User gets a unique referral code from GET /referral
Frontend builds a link: https://fonproxy.com/?ref=<code>
Visitor arrives → logs in database.
Visitor registers → invitedById is set on the new user + referrer is notified
Referred user tops up → a pending referral income transaction is created for the referrer
After 2 days (instant in dev mode) the pending transaction is credited to the referrer's balance + referrer is notified
User can track everything in GET /referral, GET /referral/graph and GET /referral/people