Events & Rewards

Stages do not watch your systems — your systems tell them what happened. Every step that matters in a referee's journey arrives as a business event, and the referral engine matches it against every active program's stages.

The Event Catalogue

Your programs react to named event types — REGISTERED, BOOKED, BILLED, PACKAGE_PURCHASED — each with a display name and, optionally, the details it carries. Stage cards suggest the events in your catalogue and accept a new name typed in; the catalogue itself is maintained with your account team over the API.

Sending an Event

An event names its type and who it happened to, and carries details the stage conditions and rewards can read — an amount, a currency, a centre code, anything your catalogue defines.

1. The platform finds every accepted referral for that lead in a program whose journey has a stage for that event type.
2. The stage's conditions are checked against the event's details. No match — nothing happens.
3. The referrer's and the referee's rewards are computed — fixed points, a percentage of a field on the event, or an expression.
4. The rewards are written as loyalty transactions, tagged with the referral and the program, and the referral's funnel stage advances.

An event that arrives for a lead with no referral is simply ignored; sending events for every customer is safe.

Firing a Stage by Hand

When the business event never reached the platform — a bill settled in a system that is not connected yet — staff can advance the referee from their profile: Update Milestone on the Referral journey fires that stage's event for them, and the rewards follow as if the event had arrived.

When Points Actually Land

A stage can also carry a Hold (days): its points are held and unlock when the hold passes, then follow the tenant's ordinary maturity and expiry rules — see Maturity & Expiry. The referee's profile shows each reward as Held, Matured, Released, Reversed, Forfeited or In review.

Reversals

Name the events that undo a conversion — a refund, a cancelled package — as the tenant's reversal events. When one arrives, the rewards fired by the matching stage are reversed for both sides through the ordinary reversal machinery: held points are forfeited, credited points are taken back under your reversal policy.

Paused Programs

With Freeze in-flight holds, events for a paused program are ignored until it resumes; with Keep advancing, referrals already in flight keep firing stages while no new referees can be captured.