Events
| Event | Description |
|---|---|
referral.updated | Referral is created or updated (universal event) |
referral.lead | Referral transitions to lead state |
referral.converted | Referral converts to paying customer |
referral.deleted | Referral is deleted |
Referral Statuses
| Status | Description |
|---|---|
CLICK | Initial click tracked, no further action yet |
LEAD | User signed up but hasn’t purchased |
TRIALING | Customer is in a trial period |
CUSTOMER | Customer made a one-time purchase |
ACTIVE | Customer has an active subscription |
CANCELED | Customer canceled their subscription |
REJECTED | Referral was rejected (fraud, policy violation) |
Payload
string
Unique event identifier
string
Event type (e.g.,
referral.converted)string
ISO 8601 timestamp of when the event occurred
object
Event payload data.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the referral
string
The affiliate who referred this customer
string
The program this referral belongs to
string
The affiliate’s tracking code used
string
Referral status (see table above)
string | null
Referred customer’s email
string | null
Customer ID from your payment provider
string | null
IP address of the referral click
string | null
The referring URL
Example Payloads
referral.lead
{
"id": "evt_abc123",
"type": "referral.lead",
"createdAt": "2024-01-15T10:30:00.000Z",
"data": {
"referralId": "ref_xyz789",
"affiliateId": "aff_abc123",
"affiliateProgramId": "prog_def456",
"trackingId": "john-doe",
"status": "LEAD",
"email": "customer@example.com",
"customerId": null,
"ip": "192.168.1.1",
"referrer": "https://blog.example.com/review"
}
}
referral.converted
{
"id": "evt_abc123",
"type": "referral.converted",
"createdAt": "2024-01-15T10:30:00.000Z",
"data": {
"referralId": "ref_xyz789",
"affiliateId": "aff_abc123",
"affiliateProgramId": "prog_def456",
"trackingId": "john-doe",
"status": "CUSTOMER",
"email": "customer@example.com",
"customerId": "cus_stripe123",
"ip": "192.168.1.1",
"referrer": "https://blog.example.com/review"
}
}
referral.deleted
{
"id": "evt_abc123",
"type": "referral.deleted",
"createdAt": "2024-01-15T10:30:00.000Z",
"data": {
"referralId": "ref_xyz789",
"affiliateId": "aff_abc123",
"affiliateProgramId": "prog_def456",
"trackingId": "john-doe",
"status": "CUSTOMER",
"email": "customer@example.com"
}
}