Referrals

Referral codes live on the tenant DB with nullable app_user_id (admin-created promo codes have app_user_id = NULL; user-owned codes are created via /client/referrals/my-code). Claims are logged in referral_claims.

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

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/referrals`	Create a promo code (admin-owned).
GET	`/admin/projects/:projectId/referrals`	List codes.
GET	`/admin/projects/:projectId/referrals/:codeId/stats`	Stats + all claims for a code.
PATCH	`/admin/projects/:projectId/referrals/:codeId`	Partial update.
DELETE	`/admin/projects/:projectId/referrals/:codeId`	Delete.

POST /admin/projects/:projectId/referrals

Request (`CreateReferralProgramInput`)

Field	Type	Required	Description
`code`	string	no	Auto-generated via `@amba/shared/referral-codes` if omitted.
`reward_referrer`	object	no	Reward paid to the referring user on claim.
`reward_referee`	object	no	Reward paid to the claiming user.
`max_uses`	number	no	Cap on claims; `null` = unlimited.

reward_referrer and reward_referee are JSONB blobs; the redemption workflow interprets them (typically { xp: 100 } or { currency: "gems", amount: 50 }).

Response 201

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

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/referrals

developer auth

curl -X POST 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/referrals'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/referrals' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/referrals

{ "data": [{ "id": "…", "code": "…", "reward_referrer": {}, "max_uses": null }] }

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/referrals

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/referrals'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/referrals' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/referrals/:codeId/stats

Response 200

{
  "data": {
    "referral_code": { "id": "…", "code": "…" },
    "total_claims": 42,
    "claims": [{ "id": "…", "claimer_id": "…", "claimed_at": "…" }]
  }
}

Errors

404 NOT_FOUND.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/referrals/%7B%7BcodeId%7D%7D/stats

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/referrals/%7B%7BcodeId%7D%7D/stats'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/referrals/{codeId}/stats' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/referrals/:codeId

Allowed fields: reward_referrer, reward_referee, max_uses, is_active.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/referrals/%7B%7BcodeId%7D%7D

developer auth

curl -X PATCH 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/referrals/%7B%7BcodeId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/referrals/{codeId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/referrals/:codeId

{ "data": { "deleted": true } }

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/referrals/%7B%7BcodeId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/referrals/%7B%7BcodeId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/referrals/{codeId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

On this page