Programs & Milestones

Creating a referral program, its lifecycle, every program setting, and the milestone journey that turns events into rewards

A program is one referral scheme. It carries its own dates, its own code format, its own channels and approval behaviour, and — most importantly — a journey: the ordered milestones a referee moves through and what each one pays. Programs live under Referrals → Programs; New program opens the settings page.

Lifecycle

Status	Meaning
Draft	Not capturing. Nobody can be enrolled or captured yet
Active	Capturing — referrers can be enrolled, referees captured, milestones fire
Paused	In-flight holds freeze, or keep advancing, per the program's When paused setting
Ended	Closed — no new referrers or referees

A new program is created as a draft; change its Status on a later edit to activate it.

One referral per patient, across all programs

A patient can be referred once — the first verified capture wins, and a second claim, even from another program, goes to the review queue as a conflict.

The Program Card

Field	Options / notes	Default
Program name	Required	—
Audience — who refers	Patients / members	Fixed
Service line	Multi-specialty, Maternity & ANC, Fertility / IVF, Nephrology, Oncology, Health-check — for grouping and reporting	Multi-specialty
Branches	Free text	All branches
Member eligibility	All members, Silver+, Gold+	All members
Start date / End date	When the program opens and closes	Open-ended
Attribution window (days)	How long a captured lead has before it expires unconverted	60
Referee auto-enrol on	Don't auto-enrol referees / When invited / When captured / When referral is accepted / When stage — the moment a referred member becomes a referrer with a code of their own	Don't auto-enrol

Capture

Field	Options / notes
Capture channels	Toggle the tenant's channels this program accepts. Channels are defined once under Settings → Loyalty → Referral
Require DPDP consent before contact	Every fresh capture is marked pending consent until a code is confirmed or consent is recorded by hand
Approval by channel	For each selected channel: Program default, Accept immediately or Needs approval. Program default follows Manual advance of a reward stage under Advanced. Fraud and two-referrer checks run on every channel regardless

See Capturing Referees for what each choice does to a capture.

Milestones & Rewards

The journey is a list of stage cards you can drag to reorder. Each stage matches an event type, optionally with conditions on the event's details, and grants a two-sided reward. The Template picker seeds a starting ladder for a Maternity program (Invited → Registered → First ANC visit); the other templates leave the builder empty for you to fill.

Part of a stage	What you choose
Stage name	“Registered”, “First appointment”, “First bill”
Event type	The business event that fires it — pick from your event catalogue or type one
Hold (days)	A waiting period before this stage's points become spendable
Referrer reward / Referee reward	Points — or, under Advanced, a Reward mode: Fixed points, % of a field (name the field, e.g. `bill_amount`), or an Expression
Add tags / Remove tags	Tags applied to that side when the reward fires
Match conditions	Rows of field, operator (=, ≠, >, ≥, <, ≤), value and type (string, number, boolean), joined by AND. None means the stage fires on the event alone

Milestone edits apply to new advances only — completed stages never re-fire.

Zero-point stages are useful

A stage that pays nothing still moves the referee along the funnel and applies its tags — use one to track “Registered” before the first paying step.

Automation Tags

Tag members the moment they become a referrer or a referee — When a member becomes a referrer and When a referee is captured, each with tags to add and remove. Tags drive CRM-bot journeys through the Tags trigger condition.

Referral Code

Prefix, generation (Random or Sequential), characters and length — see Referrers & Referral Codes. The format is fixed once the first code is issued; create a new program to use a different one.

Advanced

Setting	Options	Default
When paused	Freeze in-flight holds / Keep advancing	Freeze
Manual advance of a reward stage	Hold until verified — captures wait for a reviewer to accept the referral / Release immediately — captures are accepted on the spot	Hold until verified
Agents can release held rewards (else admins only)	Whether agents who are not administrators may decide this program's reviews	Off
Top-referrer min conversions	Conversions that make a referrer “top” on the Referrers page	5
Lapsed after (days)	Days without activity that make a referrer “lapsed”	90

Recorded, not yet enforced

Four Advanced fields are stored on the program but not read by the referral engine today: **End grace window**, **On end, un-matured holds**, **Recently-resolved window**, and **Flag bills below threshold** with its amount. Set them for the record; do not rely on them for behaviour.

The Funnel

Whatever you name your stages, the platform reports referees along a fixed funnel for analytics: Invited → Registered → Booked → Billed → Package → Completed. Capture places a referee at Invited; each fired stage advances the stage the lead is reported at.

For developers

Programs are created with `POST /api/v1/loyalty/referral/programs`, updated with `PUT …/programs/{program_uuid}`, their journey replaced with `PUT …/programs/{program_uuid}/journey`, and moved through the lifecycle with `POST …/programs/{program_uuid}/status`. The API also offers a third approval default, `APPROVE_EACH_MILESTONE`, which makes every fired milestone wait for a reviewer; the app exposes the two above.