> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Referral Events

> Webhook events for referral tracking and conversions

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

<ResponseField name="id" type="string">
  Unique event identifier
</ResponseField>

<ResponseField name="type" type="string">
  Event type (e.g., `referral.converted`)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the event occurred
</ResponseField>

<ResponseField name="data" type="object">
  Event payload data.

  <Expandable title="Data Object Properties">
    <ResponseField name="referralId" type="string">
      Unique identifier for the referral
    </ResponseField>

    <ResponseField name="affiliateId" type="string">
      The affiliate who referred this customer
    </ResponseField>

    <ResponseField name="affiliateProgramId" type="string">
      The program this referral belongs to
    </ResponseField>

    <ResponseField name="trackingId" type="string">
      The affiliate's tracking code used
    </ResponseField>

    <ResponseField name="status" type="string">
      Referral status (see table above)
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Referred customer's email
    </ResponseField>

    <ResponseField name="customerId" type="string | null">
      Customer ID from your payment provider
    </ResponseField>

    <ResponseField name="ip" type="string | null">
      IP address of the referral click
    </ResponseField>

    <ResponseField name="referrer" type="string | null">
      The referring URL
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Payloads

```json referral.lead theme={null}
{
  "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"
  }
}
```

```json referral.converted theme={null}
{
  "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"
  }
}
```

```json referral.deleted theme={null}
{
  "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"
  }
}
```