referral.* events

Referral Program lifecycle, attribution and rewards. Fires as a creator sets up the programme, as members join it and hand out their codes, as the friends they bring in arrive and pay, and as the rewards those payments earn move from held to payable, paid out or reversed. A programme pays a referrer in free membership days or in a cash commission; Subscriby never moves that money. A commission is a figure the creator pays the affiliate themselves and then records here, so the ledger these events describe is the creator's, not a payment provider's.

Four of these describe people and settings and are driven by the creator or the member. Six describe time and money: referral.captured and referral.converted are the attribution, referral.reward_earned, referral.reward_approved and referral.reward_reversed are the ledger, and referral.payout_recorded is the creator saying money left.

Background

The affiliate events nest an `affiliate` snapshot

affiliate_joined, affiliate_approved and affiliate_suspended all carry the same nested object under data.affiliate, beside the member's id and the new standing, so one consumer can handle all three:

{
  "affiliate": {
    "id": "0d1e6a2f-5c83-4b9d-9c21-7e01d6a2f594",
    "code": "K7PMQ2X",
    "status": "approved",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "days_balance": 0,
    "joined_at": "2026-11-20T09:14:02+00:00",
    "approved_at": "2026-11-20T09:14:02+00:00"
  },
  "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
  "status": "approved"
}

The snapshot never carries payout details. How an affiliate wants to be paid (a PayPal address, a wallet) is stored encrypted for the creator's dashboard and travels in no event, no broadcast and no log. Read it from the dashboard when you record a payout.

Money is a decimal string, days are an integer

amount fields are decimal strings with four decimal places ("10.0000"), never numbers: parse them as decimals, as with every amount Subscriby sends. A clawback is a negative amount. days is an integer and is null on a money row; amount and currency_id are null on a days row.