Referral events track the customer journey from initial click to conversion.
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
Event type (e.g., referral.converted)
ISO 8601 timestamp of when the event occurred
Event payload data.Show Data Object Properties
Unique identifier for the referral
The affiliate who referred this customer
The program this referral belongs to
The affiliate’s tracking code used
Referral status (see table above)
Referred customer’s email
Customer ID from your payment provider
IP address of the referral click
Example Payloads
{
"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": "[email protected]",
"customerId": null,
"ip": "192.168.1.1",
"referrer": "https://blog.example.com/review"
}
}
{
"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": "[email protected]",
"customerId": "cus_stripe123",
"ip": "192.168.1.1",
"referrer": "https://blog.example.com/review"
}
}
{
"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": "[email protected]"
}
}
