v1

latestOpenAPI 3.0.12026-08-062532117.6 KB

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.

post/referrals

Request body

affiliateIdstring

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.

affiliateEmailstring email

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

promoCodestring

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.

namestring required

Name of the referred user

emailstring email required

Email of the referred user

referredUserExternalIdstring required

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

planstring

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.

idstring uuid

The referral ID

affiliateIdstring uuid nullable

The affiliate credited with this referral

affiliateProgramIdstring uuid nullable

The affiliate program this referral belongs to

affiliateLinkIdstring uuid nullable

The affiliate link the referral came through

commissionPlanIdstring uuid nullable

The commission plan applied to this referral

namestring nullable

Name of the referred user

emailstring email nullable

Email of the referred user

referredUserExternalIdstring

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

planstring nullable

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

subscriptionStatus'ACTIVE' | 'SUBMITTED' | 'DECLINED' nullable

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

submissionType'MANUAL' | 'AUTOMATIC' nullable

Whether the referral was submitted by hand or captured automatically

referralMedium'COUPON' | 'LINK' nullable

How the referral was tracked

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

totalRevenuenumber float

Total revenue attributed to this referral

totalCommissionnumber float

Total commission generated by this referral

initialLandingPagestring nullable

The first page the referred user landed on

notesstring nullable

Free-text notes on the referral

metadataobject nullable

Arbitrary JSON you can attach to the referral

createdAtstring date-time

When the referral was created