Create a Referral
Records a new referral — someone an affiliate sent your way who has now signed up.
You must identify the affiliate with exactly one of affiliateId, affiliateEmail or promoCode. affiliateId is flexible: it accepts an affiliate UUID, one of their affiliate link slugs, or a numeric click ID.
When you pass promoCode, the code is validated first — it must exist, be active, be unexpired, and be under both its own and its coupon’s redemption limits. On success the redemption counters on the promotional code and its coupon are both incremented.
name, email and referredUserExternalId are always required. Referrals created here are always recorded as active.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The referral to create
Name of the referred user
Email of the referred user
The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
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.
Email of the affiliate to credit. Required unless affiliateId or promoCode is supplied.
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 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.
The referral ID
The affiliate credited with this referral
The affiliate program this referral belongs to
The affiliate link the referral came through
The commission plan applied to this referral
Name of the referred user
Email of the referred user
The ID you maintain for this user in your own system — for example your database user ID or a Stripe customer ID.
Plan the referred user is on. Defaults to N/A when not supplied.
Status of the referral. Referrals created through this API are always ACTIVE.
ACTIVE, SUBMITTED, DECLINED Whether the referral was submitted by hand or captured automatically
MANUAL, AUTOMATIC How the referral was tracked
COUPON, LINK Where the referral came from. Referrals created through this API have API.
UNKNOWN, API, INTEGRATION, MANUAL, IMPORTED, AFFILIATE_SUBMITTED Total revenue attributed to this referral
Total commission generated by this referral
The first page the referred user landed on
Free-text notes on the referral
Arbitrary JSON you can attach to the referral
When the referral was created