How to Set Up Multi-Level Affiliate Commissions in WooCommerce

Originally published on LumoWP. By Mansour Jabinpour. This tutorial covers our own Lumo Affiliate Engine add-on.

A normal affiliate program answers one question: who referred this order? A multi-level program adds another: should the person who introduced that affiliate receive a share too? That second question is where a simple percentage can turn into a surprisingly expensive configuration.

This tutorial walks through Lumo MLM Matrix, the multi-level commissions add-on for Lumo Affiliate Engine for WooCommerce. We will build a two-level sponsor chain, calculate the payout before enabling it, and check the records afterwards. The aim is a program you can explain to an affiliate and reconcile against an order.

What we checked: Affiliate Engine 1.95.11 and MLM Matrix 1.5.0, reviewed on 18 October 2026. The numerical results below were reproduced through the plugin’s commission services in an isolated WordPress laboratory using fictional users and orders. This was not a live payment or a full browser-checkout test. Illustrations are explanatory diagrams, not screenshots of the settings screen.

Start with the relationship, not the percentage

Imagine Maya introduces Oliver to your affiliate program. Oliver later introduces Nina. Nina sends a customer to your store, and that customer makes an eligible purchase. Nina is the direct affiliate. Oliver is Nina’s first sponsor, or Level 1. Maya is the next sponsor, or Level 2.

That numbering matters. In the add-on’s Level Rates settings, Level 1 means the direct affiliate’s sponsor. It does not mean the affiliate who generated the sale. Nina’s own commission still comes from the main Affiliate Engine commission rules.

• Customer buys through Nina → Nina receives the base referral commission.
• Nina’s sponsor is Oliver → Oliver can receive the Level 1 amount.
• Oliver’s sponsor is Maya → Maya can receive the Level 2 amount.
• A missing sponsor or the configured depth ends the chain; the plugin does not invent another recipient.

The reviewed release offers a Uni-level structure. Its Binary option is labelled coming soon and disabled. Do not plan a binary placement tree, spillover system or balanced-leg payout around that option. The implemented workflow follows recorded sponsor relationships when an eligible sale creates a base referral.

Step 1: Install the core plugin and the add-on

Use a staging copy first, particularly if your store already has affiliates or unpaid referrals. Back up the database and record your existing commission rules, order-status policy and tracking settings. Changing a rate is easy; explaining an unexpected payout after launch is harder.

1. Install and activate WooCommerce if it is not already running. Confirm that an ordinary order works before adding affiliate rules.
2. In WordPress, open Plugins → Add Plugin → Upload Plugin. Upload the Lumo Affiliate Engine ZIP, install it and activate it.
3. Activate the appropriate product license under Lumo WP → Licenses. The reviewed administration screen requires a valid license.
4. Upload and activate the separate Lumo MLM Matrix add-on ZIP from your product package. Do not upload an outer bundle containing several ZIPs as one plugin.
5. Open Lumo WP → Affiliate Settings → Addons and select MLM Matrix. Its settings include Matrix Settings, Level Rates and Visuals.

The reviewed add-on checks for Affiliate Engine 1.51.0 or newer; we inspected it with core 1.95.11. Its header specifies PHP 7.4 or newer and WordPress 6.0 or newer. These are minimum declarations, not a substitute for checking the compatibility and license requirements of the package you actually download.

If the add-on does not appear, check the Installed Plugins screen first. Both the core and the add-on must be active, WooCommerce must be available, and the core version must satisfy the dependency. If you see License Required, activate your license instead of looking for a missing settings tab.

Step 2: Establish the direct commission first

Configure a small, understandable base commission in the main plugin before adding uplines. For the example below, the direct affiliate earns 10% and the eligible commission base is $200. There are no extra product overrides or leader bonuses in this example.

Notice the phrase commission base. An order’s displayed grand total and the amount eligible for commission are not always identical. Product eligibility, discounts, tax, shipping and your main commission settings can change the calculation. Use the base recorded on the actual referral when checking an upline payment, rather than multiplying an arbitrary number from the order screen.

If you are also using store credit, keep the concepts separate: a commission owed to an affiliate and cashback credited to a buyer are different liabilities. Our affiliate commissions and wallet cashback guide explains that distinction before you combine the two.

Step 3: Build and verify the sponsor chain

The automatic sponsor-assignment path in the reviewed code runs when a WordPress user is created. It looks for a valid signed affiliate-tracking cookie and an active referring affiliate. If the new user already has a sponsor, or would sponsor themselves, the assignment is not made.

1. Prepare an active demonstration affiliate for Maya and copy her actual referral link from the affiliate area.
2. In a separate clean browser session, visit that link and create Oliver’s new WordPress account through your normal registration flow.
3. Complete whatever affiliate approval process your store requires so Oliver can participate as an active affiliate.
4. In another clean session, follow Oliver’s referral link and register Nina. Complete Nina’s affiliate approval too.
5. Open Lumo WP → Affiliate Engine → Addons → MLM Matrix → Sponsors and inspect Recent Sponsor Assignments. Confirm Oliver points to Maya and Nina points to Oliver.

Keep each registration session separate. Reusing a browser carrying an older affiliate cookie can give you the wrong tree while making the registration itself look successful. Also, activating MLM does not retroactively reconstruct who introduced existing users. A person who registered last year will not acquire an accurate sponsor merely because you enable the add-on today.

The Sponsors view in this version is a recent-assignment list, not a promise of a complete migration editor. For an established program, agree on a supported migration method before importing relationships. Avoid self-links and circular relationships. The calculation has loop protection, but a loop is still incorrect business data.

Step 4: Set depth and level rates

In Matrix Settings, enable MLM Matrix and set Depth to 2 for this walkthrough. Keep the structure on Uni-level and leave Leader Bonus disabled until the ordinary commission path has passed your tests. Save the settings, then open Level Rates.

• Level 1: 5% — paid to Oliver in our example.
• Level 2: 3% — paid to Maya in our example.
• Remove or ignore unnecessary additional rows, and ensure the depth matches the levels you actually intend to pay.
• Save and reopen the settings to verify the values persisted.

Depth is a maximum number of sponsor steps, not a guarantee that every order has that many recipients. Rates beyond the chosen depth are ignored. A level with no qualifying chain position cannot receive a commission simply because a rate exists for it.

upline amount = round(commission base × level rate ÷ 100, currency decimals)

Commission base: $200
Direct affiliate: 10% = $20
Level 1 sponsor:   5% = $10
Level 2 sponsor:   3% =  $6

The important detail is that the 5% and 3% are calculated from $200. They are not 5% and 3% of Nina’s $20 commission. That difference changes the total cost enough that it should be explained in your affiliate terms and tested before launch.

Step 5: Choose Extra or Deduct deliberately

Illustrative calculation reproduced in the local commission-service test. Rates are examples, not recommended commercial terms.

Extra payout keeps the direct commission and adds the upline amounts. In this example Nina receives $20, Oliver $10 and Maya $6: a total of $36. That is 18% of the $200 commission base, before any other rewards, costs or bonuses.

Deduct from direct affiliate subtracts the upline total from the direct affiliate’s commission. Nina receives $20 − $10 − $6 = $4. Oliver and Maya still receive $10 and $6. The total is $20 in this particular configuration.

Mode	Direct	Level 1	Level 2	Total
Extra	$20	$10	$6	$36
Deduct	$4	$10	$6	$20

Deduct is not an absolute budget cap. The reviewed code floors the direct commission at zero; it does not proportionally reduce the upline amounts. If the direct commission is $10 and the uplines total $16, the direct affiliate receives $0 and the uplines still total $16. Keep this edge case in your approval checklist.

Choose the mode that matches your actual agreement. If affiliates were promised a 10% direct rate, silently switching to a deduction model changes what they receive. Describe the net amount clearly, especially where product-specific rates or fixed direct commissions coexist with percentage-based upline rules.

Step 6: Test an order and inspect the referral records

Use fictional accounts and a sandbox or offline payment method on staging. Do not use a real customer payment merely to check the arithmetic. In our isolated service-level test, the plugin created one base referral and two MLM child referrals with the expected $20/$10/$6 amounts in Extra mode and $4/$10/$6 in Deduct mode. All were initially pending.

There is a testing trap here: the MLM handler explicitly skips base referrals marked as test referrals. The main plugin’s Test Mode therefore cannot be treated as a complete MLM validation method. Use ordinary, non-test-marked demonstration orders in an isolated environment with outbound emails and real payments disabled.

1. Make one eligible purchase through Nina’s referral path, using a separate customer account.
2. Find the order’s base referral and check its recorded commission base and direct affiliate.
3. Check the MLM records for the same order: source mlm, Level 1 and Level 2, linked to the parent base referral.
4. Compare each amount with the saved rates and currency precision.
5. Repeat with a different order in the other payout mode; changing settings is not a reason to rerun the referral-created hook manually.
6. Finally repeat through the exact checkout flow your live customers use. A service-level arithmetic test does not prove every checkout integration.

Step 7: Check approval, cancellation and paid referrals

The add-on listens for changes to the base referral status. When that referral is approved, it can approve its pending MLM children through the core commission service. When the base is rejected or cancelled, the handler rejects eligible unpaid child records.

Paid child records are excluded from that rejection path. Do not assume a refund automatically retrieves money that has already been paid to an affiliate. Before launch, test your actual order-to-referral status workflow and document how your team handles refunds after payout.

Use separate test orders for a successful sale and a cancellation. Inspect both the order and the referral records. A changed WooCommerce status alone is not enough evidence that every associated commission and balance has the intended final state.

Add leader bonuses only after the basics work

Leader Bonus adds another layer of accounting. In the reviewed implementation, an approved base referral contributes its order total to an upline’s stored team-sales counter. Crossing the configured threshold can create a fixed approved bonus, and a stored flag prevents another award through that same one-time path.

This is not a monthly salary, a recurring milestone scheme or a percentage on every team order. We also did not find a matching counter-decrement path for refunds in the reviewed leader service. Reapproval and cancellation sequences deserve their own tests before you rely on the counter for a production reward policy. Leaving this feature off for your first rollout makes the ordinary commission calculation much easier to audit.

Troubleshooting: a commission is missing or looks wrong

Symptom	What to check first
No base referral	Direct tracking, active affiliate, eligible product/order and self-referral rules.
Base exists but no uplines	MLM enabled, non-test referral, saved sponsor chain, depth and positive level rates.
Only one upline appears	Whether the next sponsor actually exists; then check depth and the Level 2 rate.
Upline amount seems too large	Calculate from the referral commission base, not from the direct commission.
Direct amount shrank	Check whether payout mode is Deduct and add the upline amounts.
Refund did not remove a payout	Check whether the child referral was already paid and review the manual recovery process.

What the source tells us—and what it does not

For this tutorial we traced SponsorService::maybe_assign_sponsor_on_register(), UplineCommissionService::handle_base_referral_created(), apply_deduct_mode() and handle_referral_status_changed(), together with the core commission service and the settings views. The local test verified the two payout calculations. It did not verify every payment gateway, registration plugin, tax setup or checkout block.

There is no need to edit those files to follow this guide. Treat the source details as an explanation of the current behaviour. Recheck the calculation and lifecycle tests after updating the core or add-on, especially if a release changes tracking or commission rules.

A practical launch checklist

• The sponsor chain is correct and all intended recipients have appropriate affiliate accounts.
• The direct rate, upline rates and maximum depth are written down in plain language.
• Extra and Deduct totals have been checked against the margins of eligible products.
• A successful order and a cancelled order have been tested through the real checkout configuration on staging.
• Your team knows how to reconcile the parent referral and its MLM children.
• Refunds after payout and leader bonuses have explicit operational rules.

Start with a small tree and two understandable rates. Once you can explain where every dollar in one order went, expanding the program becomes a deliberate configuration decision instead of a guess.