Referral Program — Configuration
Last updated: September 9, 2026
Tab Configuration on /admin/referrals — six blocks with Save-
button. Every change writes a referral.config_updated audit-
entry with diff (referral.program_toggled for the master switch).
Block: Program Status
| Field | Meaning |
|---|---|
| Program Enabled | Master switch; off = new redemptions blocked |
| Show Marketing Banner | Controls the /referral landing page + the header banner on the marketing site |
| Terms Link | Required field — the program cannot be enabled without URL |
Block: Referrer Reward
| Field | Meaning |
|---|---|
| Reward Type | credit (Stripe balance), coupon (Stripe coupon), trial_extension (trial days) |
| Value (Cents) | For credit — booked on Stripe as negative balance_transaction |
| Currency | ISO code, for credit |
| Coupon ID | For coupon — must exist in Stripe |
| Days | For trial_extension — only effective if referrer is still trialing |
Block: Referee Reward (Double-Sided)
Own toggle. If on, the referee gets at registration the same reward — either Stripe credit (immediately) or coupon. Trial extension on the referee is possible but rarely useful (new tenant has the full trial anyway).
Block: Qualifying & Lifecycle
| Field | Meaning |
|---|---|
| Qualifying Trigger | first_paid_invoice (default), trial_converted, n_days_paid |
| Days | For n_days_paid — referral qualifies if the first payment is at least N days old |
| Expiration (Days) | If referee does not qualify within this period → status Expired |
| Clawback Window (Days) | If referee cancels within the period after reward → credit reversal |
Block: Eligibility & Limits
| Field | Meaning |
|---|---|
| Excluded Plans | CSV list of plan slugs — referrers on these plans do not earn (default: trial) |
| Max. per Period | Per referrer × 30 days; further redemptions go into the next period |
| Lifetime Cap (Cents) | Sum of all rewards per referrer; after that admin approval |
| Monthly Cap (Cents) | Per referrer × month |
| Platform Monthly Budget (Cents) | Global reward budget; after that pause |
| Manual Review Threshold (Cents) | Individual rewards above this value need admin approval |
Block: Notifications
Eight toggles control the emails + in-app notifications. The underlying templates can be edited under /admin/emails/templates (Subject + Body + Variables):
referral_redeemed— to referrer when someone redeems their code.referral_qualified— to referrer when referral qualifies.referral_rewarded— to referrer when reward is booked on Stripe.referral_clawback— to referrer when reward is revoked.referral_expired— informational, default off.referee_welcome_with_reward— to referee for double-sided.referral_grant_failed_admin— internal alert when Stripe fails.- In-App Notifications — Bell icon toast in the referrer dashboard.
Best Practices
- Activation: set terms link, create the Stripe coupon (if
couponreward) first, then enable the program. - Test: before roll-out to all tenants — enter a test coupon ID, refer a test account, check that cron + Stripe run the full pipeline.
- Budget Protection: set the platform monthly budget before the campaign is publicly advertised.