Referral API

Base path: /api/referral

Manages the referral program: link generation, conversion tracking, and reward statistics. Referrers earn 5 extra AI generation credits per successful conversion.

GET /api/referral/link

Get the authenticated user's unique referral link. If the user does not yet have a referral code, one is generated automatically (8-character uppercase hex string).

Auth: Required (JWT) Feature gate: None

Response:

{
  "success": true,
  "data": {
    "code": "A1B2C3D4",
    "link": "https://app.creatiq.com/login?ref=A1B2C3D4"
  }
}

Field	Type	Description
`code`	`string`	8-character uppercase referral code
`link`	`string`	Full referral URL pointing to the login page with `ref` query parameter

Errors:

Status	Body	Condition
500	`{ "success": false, "error": "Failed to get referral link" }`	User not found or database error

POST /api/referral/convert

Process a referral code during a new user's registration. This endpoint:

Looks up the referrer by referralCode.
Records the conversion in the referrals table.
Links the new user to the referrer (referred_by column).
Awards the referrer 5 bonus AI generation credits.

All steps run inside a database transaction.

Auth: None (public -- called during registration) Feature gate: None

Request body:

{
  "referralCode": "A1B2C3D4",
  "email": "newuser@example.com"
}

Field	Type	Required	Constraints
`referralCode`	`string`	Yes	Min 1, max 20 characters
`email`	`string`	Yes	Valid email, max 255 characters

Response (success):

{
  "success": true,
  "data": {
    "converted": true,
    "referrerId": "referrer-uuid"
  }
}

Response (invalid code):

{
  "success": true,
  "data": {
    "converted": false,
    "referrerId": null
  }
}

Field	Type	Description
`converted`	`boolean`	Whether the referral was successfully processed
`referrerId`	`string \| null`	UUID of the referrer, or `null` if the code was invalid

Errors:

Status	Body	Condition
400	`{ "success": false, "error": "Validation error: ..." }`	Zod validation failure
500	`{ "success": false, "error": "Failed to convert referral" }`	Database or transaction error

GET /api/referral/stats

Get referral statistics for the authenticated user.

Auth: Required (JWT) Feature gate: None

Response:

{
  "success": true,
  "data": {
    "totalReferrals": 10,
    "convertedReferrals": 6,
    "pendingReferrals": 4,
    "totalRewards": 30
  }
}

Field	Type	Description
`totalReferrals`	`number`	Total referral records for this user
`convertedReferrals`	`number`	Referrals with status `converted`
`pendingReferrals`	`number`	Referrals with status `pending`
`totalRewards`	`number`	Total bonus credits earned (convertedReferrals x 5)

Errors:

Status	Body	Condition
500	`{ "success": false, "error": "Failed to get referral stats" }`	Database error