Affiliates & Referrals

/affiliates

Referral program. Affiliates are created by administrators and identified by a unique referral code; a referral links one signed-up user to one affiliate, and the affiliate earns a percentage commission (`commissionRate`) on that user's subscription payments. These endpoints let a signup flow validate a referral code and record the referral, and let an affiliate view their own performance. Affiliate management endpoints are admin-only and not documented here.

GET/affiliates/my-statsGet the authenticated affiliate's stats GET/affiliates/validate/:codeValidate a referral code POST/affiliates/referralRecord a referral for the authenticated user

GET/affiliates/my-stats

Get the authenticated affiliate's stats

Auth required

Affiliate dashboard data for the logged-in user. The user is treated as an affiliate when an affiliate record exists whose `email` equals the user's account email; otherwise the endpoint responds 404 with `{ "isAffiliate": false }`. `totalRevenueCents` is the sum of all tracked subscription payments made by referred users and `totalCommissionCents` is `round(totalRevenueCents * commissionRate / 100)`. The monthly figures are computed live from Stripe: the sum of paid subscription invoices created during the current calendar month (server time) by referred users, with `monthlyCommissionCents` derived using the same commission formula. `activeSubscriptions` counts referrals whose `subscriptionStatus` is `active`. All referrals are returned (no pagination), exposing only the referred user's username, subscription status (`none`, `active`, `canceled`, `past_due` or `trialing`) and referral date; `username` is "Unknown" if the user no longer exists. `referralLink` is the frontend base URL with `?ref=<code>` appended.

Errors

401No bearer token provided (plain text: "Unauthorized: No token provided")
403Token is invalid or expired (plain text: "Forbidden: Invalid token")
404The authenticated user's email does not match any affiliate (JSON: `{ "isAffiliate": false }`)
500Database or Stripe lookup failed (JSON: `{ "error": "Failed to fetch affiliate stats" }`)

Request

curl -X GET "https://app.ummahspot.com/affiliates/my-stats" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "isAffiliate": true,
  "affiliate": {
    "name": "Ahmad Khan",
    "code": "ahmadkha",
    "referralLink": "https://sharh.io?ref=ahmadkha",
    "commissionRate": 20,
    "isActive": true,
    "createdAt": "2026-01-12T09:30:00.000Z"
  },
  "stats": {
    "totalReferrals": 14,
    "activeSubscriptions": 6,
    "totalRevenueCents": 18500,
    "totalCommissionCents": 3700,
    "monthlyRevenueCents": 3000,
    "monthlyCommissionCents": 600,
    "currentMonth": {
      "year": 2026,
      "month": 9,
      "monthName": "September"
    }
  },
  "referrals": [
    {
      "id": "66eae1b2c3d4e5f6a7b8c9d0",
      "username": "talib_ilm",
      "subscriptionStatus": "active",
      "createdAt": "2026-08-02T17:45:10.000Z"
    }
  ]
}

GET/affiliates/validate/:code

Validate a referral code

Public

Public lookup used by the signup flow to check a referral code. A code is valid only if an affiliate with exactly that code exists (case-sensitive match) and is active; deactivated affiliates are reported as invalid. On success only the affiliate's display name is revealed.

Path parameters

code

string

Affiliate referral code, e.g. the `ref` value of a referral link

Errors

404No active affiliate has this code (JSON: `{ "valid": false }`)
500Lookup failed (JSON: `{ "error": "Failed to validate code" }`)

Request

curl -X GET "https://app.ummahspot.com/affiliates/validate/:code"

Response · 200

{
  "valid": true,
  "affiliateName": "Ahmad Khan"
}

POST/affiliates/referral

Record a referral for the authenticated user

Auth required

Attributes the authenticated caller to an affiliate. The referred user is always the user behind the bearer token; it cannot be supplied in the body, so a referral can only be recorded for yourself. The affiliate must exist and be active, and a user can only ever have one referral: a second attempt is rejected regardless of the code. The new referral starts with subscription status `none`; its subscription status and payment totals are then kept up to date automatically from Stripe events. Most clients never need this endpoint: POST /user/signup (body field `referralCode`) and the Google OAuth flow (`ref` query parameter on GET /user/auth/google) already record the referral server-side when a referral code is supplied at signup.

Body parameters

affiliateCoderequired

string

Referral code of an active affiliate (exact, case-sensitive match).

Errors

400`affiliateCode` missing (`{ "error": "Affiliate code is required" }`), or the authenticated user already has a referral (`{ "error": "User already has a referral recorded" }`)
401No bearer token provided (plain text: "Unauthorized: No token provided")
403Token is invalid or expired (plain text: "Forbidden: Invalid token"), or the user has none of the member, editor or admin roles
404Code does not belong to an active affiliate (`{ "error": "Invalid or inactive affiliate code" }`), or the user behind the token no longer exists (plain text: "User not found")
500Database failure (JSON: `{ "error": "Failed to record referral" }`)

Request

curl -X POST "https://app.ummahspot.com/affiliates/referral" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"affiliateCode":"string"}'

Response · 201

{
  "message": "Referral recorded successfully"
}