Multilevel Referral

Optional add-on to the Referral Program. Pays out commissions up the chain of sponsors — up to 10 levels deep — when an invitee places their first completed order.

Setting up?

Skip to Multilevel Settings for the step-by-step admin tab walkthrough (levels, per-level commissions).

What It Does

For	Means
Customer	"I sponsor someone, they sponsor someone else, I still earn a small cut." Same dashboard — chain rewards roll into "Earned" total
Admin	Configurable depth (1-10) and per-level percent. Off by default — turn on only when you want chain commissions

Wallet Central right rail — referral entry; chain commissions roll into the "Earned" total here

The admin toggles for chain depth + per-level commissions:

Multilevel Referral admin section — enable, levels (1-10), per-level percentages

When You'd Use This

Scenario	Use multilevel?
Single-level referrer reward	NO — base Referral Program is enough
Affiliate network with 2-3 sponsor tiers	YES
Influencer chain (sponsor pays up the chain)	YES
MLM-style network marketing	YES (review legal compliance per jurisdiction)

How It Works

Invitee D was invited by C. C was invited by B. B was invited by A.

A  (Level 3 sponsor)
  ↑
B  (Level 2 sponsor)
  ↑
C  (Level 1 sponsor — direct referrer)
  ↑
D  (the new customer placing first completed order)

When D's first order completes:

C (direct) gets the base referral reward — same as single-level program
Multilevel engine walks up: D → C → B → A (stops at configured depth)
For each ancestor, apply that level's percentage to the base amount → credit ancestor wallet

Each credit is its own audit row tagged with the level number.

The level-1 commission entry is informational only — the direct referrer is paid the full base by the single-level engine. Set the level-1 value to whatever you want shown on a "How rewards work" page, or leave it as a marker.

Example

Base referrer reward 100, levels = 3, commissions [10, 5, 2]:

Level	Sponsor	Reward
1	C (direct)	`100` (full base — paid by single-level engine)
2	B	`100 × 5%` = `5`
3	A	`100 × 2%` = `2`

When a time-boxed promo is active, the multiplier wraps the base before multilevel resolves it.

So during a 2× promo with base 100:

Level	Sponsor	Reward
1	C	`200`
2	B	`200 × 5%` = `10`
3	A	`200 × 2%` = `4`

Promo applies to every level, not just direct.

Customer Dashboard

The customer side doesn't show a chain visualization (intentional — keeps the dashboard simple). The "Earned" total includes chain credits silently.

For an admin-side chain view, filter ledger by type = referral + reference contains level.

Common Scenarios

3-tier influencer programme

Levels 3, commissions [15, 7, 3]. Top tier earns 15%, second 7%, third 3% of the base reward.

Disable temporarily without losing settings

Toggle "Enable" → OFF. Ancestry walk skipped entirely. Only direct (single-level) rewards fire.

Audit chain payouts for a specific order

In Wallet → Transactions, filter by type = referral and search reference for the order ID — you'll see one row per level paid out.

When Something Goes Wrong

Problem	Fix
Multilevel not crediting	Enabled? Friend's first order in `completed`? Ancestry chain populated when friend signed up?
Level-N percent not applied	Is N within "Levels" config? Has a value in the per-level array?
Promo multiplier missed	Order's `completed` timestamp inside the start/end window?
Ancestry empty	Sponsor was deleted before the friend signed up — chain enrichment ran on an orphan

For developers — hooks + ancestry walk

Worker

WKWP_Referral_Signup_Enricher:

On user_register — caches ancestry_chain (CSV of ancestor IDs in order)
On woocommerce_order_status_completed priority 25 — walks the cached chain

Caching ancestry on signup means first-completed-order doesn't re-walk the chain (avoids race conditions if a sponsor was deleted later).

Hooks

Hook	Type	When
`wkwp_multilevel_levels_active`	filter	mutate active level count per order
`wkwp_multilevel_commission_percent`	filter	mutate per-level % at runtime
`wkwp_multilevel_credited`	action	per-level credit row written
`wkwp_multilevel_chain_resolved`	action	ancestry walk done

Idempotency

Each (referrer_id, invitee_id, level) is unique. Re-running order completion is a no-op for already-paid levels.

Zero-cost when disabled

_wkwp_multilevel_enable = 0 short-circuits the entire engine. Zero performance cost on stores that don't want chain commissions.

Setting	Default	What it does
Enable	OFF	global toggle
Levels	`3`	how many levels deep to walk (1-10)
Per-level commissions	`[10, 5, 2]`	percent at each level (index 0 = level 1)