Referral Program
Each customer gets a unique referral link. Friends sign up, place a first order, both sides get rewarded — referrer earns wallet credit, invitee gets a first-order discount.
Setting up?
Skip to Referral Settings for the step-by-step admin tab walkthrough (referrer reward, referee coupon, cookie window, promo multiplier).
What It Does
| For | Means |
|---|---|
| Customer | Personal share link with a Copy button + WhatsApp / X / Email / Messenger share buttons |
| Friend | Lands on the store, signs up, gets a WELCOME-XXXXXX first-order coupon. Both sides happy on first order |
| Admin | Whole flow on autopilot. Optional time-boxed promo to double rewards. Pairs with Multilevel Referral for chain commissions |
How It Works
1. Referrer shares link (e.g. https://yourstore.com/?ref=BOB22)
2. Friend lands → 7-day cookie set
3. Friend registers → wallet_referrals row written → WELCOME coupon emailed
4. Friend places first completed order → both get rewarded
- Referrer: wallet credit
- Invitee: WELCOME coupon already redeemed at checkout
Referral Codes
Each customer gets a unique alphanumeric code automatically (e.g. BOB22, AARAV42). Generated from their login + ID, cached on first need.
Customers can find their code on:
- My Wallet → Referral panel (the Copy button)
- Wallet Central → Refer & earn
Admin can regenerate from the user profile Wallet card.
The right-rail card on the Wallet Central home holds the Refer & earn entry alongside payees / linked accounts / limits / refundable orders:
Backward compatible
Both ?ref=BOB22 (alpha code) and ?ref=42 (legacy numeric user-id) resolve to the same user. No URLs break across upgrades.
Reward Trigger
The referrer is credited on the invitee's first completed order — not on signup.
Why? Avoids paying out on registration spam and abandoned carts.
Setup
Wallet → Settings → Referral
| Setting | Default | What it does |
|---|---|---|
| Enable | OFF | global toggle (zero overhead when off) |
| Referrer reward type | fixed | fixed / percent |
| Referrer reward amount | 100 | currency value or % |
| Referrer max cap | empty | optional ceiling per referral |
| Referee coupon type | fixed_cart | the type of WC coupon minted for the friend |
| Referee coupon amount | 50 | discount value |
| Cookie days | 7 | attribution window |
| Promo enable | OFF | optional time-boxed multiplier |
| Promo start / end / multiplier | empty | window + boost (e.g. 2× during launch fortnight) |
| Description (dashboard) | empty | rich text shown above the customer's referral panel |
| How-it-works steps (3) | defaults | rich text for the 3-step explainer card |
Referee First-Order Coupon
Auto-generated for every invitee:
- Code:
WELCOME-XXXXXX(random suffix) - Single-use, restricted to the invitee's email
- First-order only (enforced server-side)
- Type:
fixed_cartorpercent
Sent via the standard WC coupon email. Invitee redeems normally at checkout.
Time-Boxed Promo Multiplier
Boost rewards during a campaign window without rewriting your base rule.
| Setting | Example |
|---|---|
| Enable | ON |
| Start | 2026-04-01 00:00 |
| End | 2026-04-30 23:59 |
| Multiplier | 2 (double) |
During the window:
- Referrer reward × 2
- Multilevel chain rewards × 2 (if multilevel enabled)
- Customer dashboard shows a live countdown chip
After the window, multiplier auto-deactivates — no admin action needed.
Customer Dashboard
Both surfaces show the same panel:
- Personal link pill + Copy button
- Brand-coloured share buttons (WhatsApp / X / Email / Messenger)
- 3-step "How it works" card
- "Your invites" list
- Stats: total earned / invited / signed up / pending
Common Scenarios
Customer says they invited a friend but no reward
Check:
- Did the friend register through the link (cookie set)?
- Did the friend's first order complete (not just
processing)? - Is the customer's referral status visible in the admin user profile?
If all yes → check ledger for the referral row. Cache may be stale.
Friend's WELCOME coupon doesn't apply at checkout
WC coupon is email-restricted. Confirm the friend's checkout email matches the registration email.
Customer's referral code not generating
Open their user profile → Wallet card → Regenerate referral code button.
Run a launch promo
Set promo start/end + multiplier. Customer dashboard shows the countdown chip until the window closes. After end, base rewards resume.
When Something Goes Wrong
| Problem | Fix |
|---|---|
| Code doesn't resolve | Regenerate via Users → [user] → Wallet card |
| Reward not credited | Order in completed? Friend visited via link? Already paid? |
| Cookie not set | Browser blocking 3rd-party cookies — share via direct link only |
| Coupon not in friend's email | Email mismatch; confirm friend's account email matches the cookie attribution |
| Promo multiplier not active | Check start/end dates + server timezone |
For developers — hooks + storage + idempotency
Hooks
| Hook | Type | When |
|---|---|---|
wkwp_referral_base_amount | filter | mutate referrer payout (used by promo + multilevel) |
wkwp_referral_register_resolved | action | ?ref= value resolved on registration |
wkwp_referral_reward_credited | action | referrer credit row written |
wkwp_referral_first_order_coupon_created | action | invitee coupon minted |
wkwp_referral_cookie_days | filter | mutate cookie TTL |
Idempotency
wallet_referrals UNIQUE on (referrer_id, invitee_id) — prevents double-payout. Reward only credits when reward_amount > 0 lock acquired atomically.
Admin gate
Every hook early-returns when _wkwp_referral_enable = 0. Zero side-effects on auth / registration / order flow when disabled.
Cookie
Name wkwp_ref, TTL 7 days, HttpOnly + SameSite=Lax + Secure on HTTPS. First-touch wins (existing cookie not overwritten).
Tested
Unit + integration + Playwright regression in tests/unit/referral/ and tests/e2e/specs/referral/.