Referrals

Each user gets their own code lazily (first read creates it). Rewards are paid server-side on claim — both reward_referrer and reward_referee are honored, clamped to any currency max_balance, and logged to currency_transactions under source = 'referral'.

Source: apps/api/src/routes/client/referrals.ts.

Endpoints

GET /client/referrals/my-code

If the user already has a code, returns it. Otherwise a new code is generated (with up to 5 retries on 23505 unique_violation). Rewards are copied from the first admin-created template code (app_user_id IS NULL) if one exists.

Response 200 (existing) / 201 (newly created)

{
  "data": {
    "id": "…",
    "app_user_id": "…",
    "code": "X3Q9K2",
    "reward_referrer": {},
    "reward_referee": {},
    "current_uses": 0,
    "max_uses": null,
    "is_active": true
  }
}

Errors

• 500 RETRY_EXHAUSTED — could not generate a unique code after 5 attempts.
• 500 CREATE_FAILED.

Try it:

curl -X GET 'https://api.amba.dev/client/referrals/my-code'

Curl:

curl -X GET '${BASE_URL}/client/referrals/my-code' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/referrals/claim

All validation + the referral_claims insert + the current_uses increment run under FOR UPDATE on the code row so concurrent claims serialize. Reward grants run post-commit as best-effort — a grant failure is logged but the claim succeeds (operators reconcile from currency_transactions).

Request

Response 201

{
  "data": {
    "id": "…",
    "referral_code_id": "…",
    "referrer_id": "…",
    "referee_id": "…",
    "claimed_at": "…"
  }
}

Errors

• 400 SELF_REFERRAL — the code belongs to the caller.
• 400 MAX_USES_REACHED — code hit its use cap.
• 400 ALREADY_CLAIMED — caller has already claimed this code.
• 404 INVALID_CODE — code not found or inactive.
• 500 CLAIM_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/client/referrals/claim'

Curl:

curl -X POST '${BASE_URL}/client/referrals/claim' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'