Skip to main content
POST
Create a referral

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The referral to create

name
string
required

Name of the referred user

email
string<email>
required

Email of the referred user

referredUserExternalId
string
required

The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.

affiliateId
string

Identifies the affiliate to credit. Accepts an affiliate UUID, one of their affiliate link slugs, or a numeric click ID. Required unless affiliateEmail or promoCode is supplied.

affiliateEmail
string<email>

Email of the affiliate to credit. Required unless affiliateId or promoCode is supplied.

promoCode
string

A promotional code belonging to the affiliate to credit. Required unless affiliateId or affiliateEmail is supplied. The code is validated for existence, active state, expiry and redemption limits, and its redemption counters are incremented on success.

plan
string
default:N/A

Plan the referred user signed up on.

Response

The created referral, looked up by email after creation. Returns null if the referral could not be resolved.

id
string<uuid>

The referral ID

affiliateId
string<uuid> | null

The affiliate credited with this referral

affiliateProgramId
string<uuid> | null

The affiliate program this referral belongs to

The affiliate link the referral came through

commissionPlanId
string<uuid> | null

The commission plan applied to this referral

name
string | null

Name of the referred user

email
string<email> | null

Email of the referred user

referredUserExternalId
string

The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.

plan
string | null

Plan the referred user is on. Defaults to N/A when not supplied.

subscriptionStatus
enum<string> | null

Status of the referral. Referrals created through this API are always ACTIVE.

Available options:
ACTIVE,
SUBMITTED,
DECLINED
submissionType
enum<string> | null

Whether the referral was submitted by hand or captured automatically

Available options:
MANUAL,
AUTOMATIC
referralMedium
enum<string> | null

How the referral was tracked

Available options:
COUPON,
LINK
source
enum<string>

Where the referral came from. Referrals created through this API have API.

Available options:
UNKNOWN,
API,
INTEGRATION,
MANUAL,
IMPORTED,
AFFILIATE_SUBMITTED
totalRevenue
number<float>

Total revenue attributed to this referral

totalCommission
number<float>

Total commission generated by this referral

initialLandingPage
string | null

The first page the referred user landed on

notes
string | null

Free-text notes on the referral

metadata
object | null

Arbitrary JSON you can attach to the referral

createdAt
string<date-time>

When the referral was created

Last modified on July 20, 2026