Referral API
FonProxy referral endpoints: get referral info, update codes, view referral graph and earnings.
Updated 2026-04-09 16:13:00
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) |
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": "#E6318B",
"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 β
invitedByIdis 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 /referralandGET /referral/graph