Overview
The MLM Affiliate module adds a complete multi-level marketing and affiliate commission system to your Odoo 18 store. When a referred customer places a confirmed and paid order, the system automatically calculates and distributes commissions to every level of the referrer's upline chain — all without manual intervention.
via referral link
per level, pending
auto-approved
or bank payout
Key Capabilities
| Feature | Description |
|---|---|
| Multi-level commissions | Distribute a commission pot across unlimited upline levels with configurable percentage rates per level. |
| Pricelist-aware rules | Different commission rates for reseller, VIP, or wholesale pricelists vs. the public pricelist. |
| Affiliate wallet | Commissions credited to a wallet balance that affiliates can spend at checkout — no cash withdrawal needed. |
| Payout requests | Affiliates submit payout requests via the portal; admin approves and marks as paid. |
| Tier system | Automatic tier promotion (Bronze → Silver → Gold → Diamond) based on earnings and referral count, with tier commission multipliers. |
| Campaigns | Time-limited commission boosts for specific affiliates with optional buyer promo codes. |
| Milestone bonuses | One-time bonus commissions when affiliates cross earnings or referral thresholds. |
| Accounting | Approved commissions automatically create debit/credit journal entries. |
| Fraud protection | Self-referral prevention, affiliate application approval, commission hold period. |
| Refund clawback | Commissions automatically cancelled when the linked invoice is reversed. |
Installation
Download the module
Download mlm_affiliate_v2_30_fixed.zip and extract it to your Odoo custom addons directory (e.g. F:\odoo_dev\odoo18\custom_addons\). The extracted folder must be named mlm_affiliate.
Restart the Odoo server
Stop and restart the Odoo service so the new addon directory is picked up. In development: python odoo-bin -d yourdb -u all or restart the service.
Activate Developer Mode
Go to Settings → General Settings, scroll to the bottom and click Activate the developer mode. This is required to see the Apps list with technical modules.
Install the module
Go to Apps, remove the "Apps" filter in the search box, search for MLM Affiliate, and click Install.
Complete first-time setup
After installation, the post-install hook automatically creates two accounts (501108, 300201) and one journal (MLMC), and links them to Settings. Verify in Settings → MLM Affiliate.
If you previously had a version with the MLM-EXP / MLM-PAY account code error, upgrade to v2.30 (18.0.2.18.0) and the migration script will automatically link the accounts/journal to your MLM settings on the first server start.
First-time Setup
After installation, follow these steps in order before going live.
1. Verify accounting links
Go to Settings → MLM Affiliate → Accounting and confirm all three fields are filled:
2. Configure commission level rates
Go to MLM Affiliate → Configuration → Level Rates. The default rates are pre-installed. Adjust to match your business model. Rates do not need to sum to 100% — any unallocated percentage stays with the company.
| Level | Description | Default Rate |
|---|---|---|
| Level 1 | Direct referrer (the affiliate who shared the link) | 60% |
| Level 2 | Their upline sponsor | 20% |
| Level 3 | Second-level upline | 10% |
3. Create your first commission rule
Go to MLM Affiliate → Configuration → Commission Rules → New. Set a rule for your main product category with a percentage commission pot.
4. Create your affiliate tiers
Go to MLM Affiliate → Configuration → Affiliate Tiers. Create at least a basic tier with min_earned = 0 so that all affiliates are assigned to something.
5. Set the admin partner
In Settings → MLM Affiliate → Commission Settings, set the Admin Account. This partner receives commission amounts for any MLM level that has no upline partner in the chain.
Settings
All MLM settings are under Settings → MLM Affiliate.
| Setting | Effect | Recommended |
|---|---|---|
| Admin Account | Receives "orphan" commissions where no upline exists at a level | Your company's main partner or a dedicated MLM admin account |
| Minimum Payout Amount | Blocks marking commissions as Paid if amount is below threshold | 500 – 1000 to reduce payment overhead |
| Commission Hold Period | New commissions locked for N days — cannot be approved until hold expires | Match your return policy (14–30 days) |
| Require Application Approval | New affiliates need admin approval before earning commissions | Enabled for controlled programs |
| Send Monthly Summary | Automatic email to all affiliates on the 1st of each month with previous month's earnings | Enabled — keeps affiliates engaged |
Commission Rules
Commission rules define how much of a sale goes into the "commission pot" — the total amount that is then split across MLM levels. Rules are found under MLM Affiliate → Configuration → Commission Rules.
Rule types (priority order)
| Priority | Type | Matches |
|---|---|---|
| 1 (highest) | Specific Variant + Pricelist | One product variant on a specific pricelist |
| 2 | Product Template + Pricelist | All variants of a product on a specific pricelist |
| 3 | Category + Pricelist | All products in category tree on a pricelist |
| 4 | Specific Variant | One product variant (any pricelist) |
| 5 | Product Template | All variants of a product (any pricelist) |
| 6 (lowest) | Category | All products in category tree (any pricelist) |
Create one rule for your root product category (e.g. "All" or "Saleable") at a low commission percentage. Then override specific products or categories with higher rates. This ensures every product generates some commission.
Commission types
| Type | Calculation | Example |
|---|---|---|
| Percentage (%) | price_subtotal × rate ÷ 100 | 10% on a $200 order → $20 pot |
| Fixed Amount | fixed_amount × qty | $5 fixed on a 3-unit order → $15 pot |
Level Distribution Rates
Level rates define what percentage of the commission pot each upline level receives. Go to MLM Affiliate → Configuration → Level Rates.
How the commission pot is split
Given a 10% commission rule on a $300 order (pot = $30) and these level rates:
└─ Level 1 (60%) → Direct Referrer: $18.00
└─ Level 2 (20%) → Their Sponsor: $6.00
└─ Level 3 (10%) → Second Upline: $3.00
└─ Remaining (10%) → Company (unallocated): $3.00
Unallocated percentages simply stay with the company. This makes it easy to add or remove levels without rebalancing every other rate.
Affiliate Tiers
Tiers are automatically assigned when an affiliate's lifetime earnings and/or direct referral count cross the configured thresholds. Go to MLM Affiliate → Configuration → Affiliate Tiers.
0+ referrals
3+ referrals
10+ referrals
30+ referrals
Tier multipliers stack with campaign multipliers. A Gold affiliate on an active 1.2× campaign earns 1.25 × 1.2 = 1.5× on all commissions during the campaign period.
If no tier matches an affiliate, their tier_id is set to empty and no multiplier is applied. A Bronze tier at $0 ensures every affiliate is always in a tier.
Campaigns
Campaigns give a specific affiliate a time-limited commission boost. Go to MLM Affiliate → Campaigns → New.
| Field | Description |
|---|---|
| Affiliate | Which affiliate gets the boost |
| Start / End Date | Campaign is active between these dates (inclusive) |
| Commission Multiplier | All commissions earned during this period are multiplied. 1.5 = 50% bonus |
| Buyer Promo Code | A code you can share with buyers — not yet wired to checkout discounts (coming in v2.32) |
Only one campaign per affiliate is active on any given date. If multiple campaigns overlap for the same affiliate, only the first one found is applied (ordered by start date desc). Plan campaigns to avoid overlaps.
Milestones
Milestones are one-time bonus commissions awarded automatically when an affiliate crosses a threshold. Go to MLM Affiliate → Configuration → Milestones.
| Field | Description |
|---|---|
| Milestone Name | Displayed in the commission record note (e.g. "First $1,000 Earned") |
| Min. Total Earned | Lifetime commission earnings threshold |
| Min. Direct Referrals | Number of direct downline partners required alongside the earning threshold |
| Bonus Amount | Fixed bonus credited to the affiliate's wallet as an approved commission |
Milestone checks run automatically after every tier update — which happens after each commission approval. Each milestone is awarded at most once per affiliate.
Managing Affiliates
Affiliates are standard Odoo contacts (res.partner) with the Is Affiliate flag enabled. Find them under MLM Affiliate → Affiliates, or in Contacts with the "Affiliate" filter.
Creating an affiliate manually
Open the contact form
Go to Contacts → New (or find an existing customer).
Enable Is Affiliate
Check the Is Affiliate / Referrer checkbox in the MLM Affiliate tab. A referral code is auto-generated.
Set the upline (optional)
In the Referred By (Upline) field, select the affiliate who recruited this person. This determines the commission chain.
Share the referral link
The Referral Link field shows the full URL. Copy it and send to the affiliate — they share this with potential customers.
Affiliate application flow (when enabled)
When Require Application Approval is enabled in settings, new affiliates registered via the portal start with affiliate_status = pending and cannot generate commissions until approved.
via /affiliate portal
application
→ can earn
To approve: open the partner form → click Approve Affiliate button. To reject: click Reject Affiliate.
Commissions
Commission records are found under MLM Affiliate → Commissions. Each record represents one commission earned by one affiliate for one order line at one level.
| Reference | Earner | Sale Order | Level | Amount | Payout | Status |
|---|---|---|---|---|---|---|
MLM/2026/0042 |
Sarah Ahmed | S00142 | L1 (60%) | ৳ 1,800 | Wallet | Approved |
MLM/2026/0043 |
Rahim Khan | S00142 | L2 (20%) | ৳ 600 | Bank | Approved |
MLM/2026/0044 |
Mina Begum | S00143 | L1 (60%) | ৳ 2,400 | Wallet | Pending |
MLM/2026/0045 |
Karim Hossain | S00143 | L2 (20%) | ৳ 800 | Wallet | On Hold |
Commission states
| State | Meaning | Transition |
|---|---|---|
| Pending | Created when sale order confirmed. Not yet payable. | Auto-approved when invoice is paid (if no hold period active) |
| Approved | Commission is valid and included in wallet balance. | Manually click "Mark as Paid" or via payout request |
| Paid | Deducted from wallet or paid out via bank. Final state. | — |
| Cancelled | Commission void — refund received or manually cancelled. | Can reset to Pending if needed |
On-hold commissions
If a Commission Hold Period is configured in settings (e.g. 14 days), newly created commissions are locked with a hold_until date. The auto-approval cron runs nightly and releases held commissions once their hold date passes.
Payout Requests
Affiliates submit payout requests from the portal. Admins review and process them under MLM Affiliate → Payout Requests.
Payout workflow
Processing a payout request
Review the request
Open the request. Check the affiliate's bank account, amount requested, and the linked commission records.
Approve
Click Approve. The request moves to Approved state. The commissions are not yet marked as paid.
Process payment externally
Transfer the amount to the affiliate's bank account or mobile wallet via your banking system.
Mark as Paid
Click Mark as Paid. All linked commissions are automatically moved to Paid state. The affiliate's wallet balance updates immediately.
If a minimum payout amount is set in Settings, attempting to mark a commission as Paid when its amount is below the threshold will raise a validation error. The threshold applies per commission record, not per payout request total.
Accounting Integration
When a commission is approved, the system automatically posts a journal entry to record the liability.
| Account | Side | Code | Purpose |
|---|---|---|---|
| MLM Commission Expense | Debit | 501108 | Records the cost as a marketing/sales expense |
| MLM Commission Payable | Credit | 300201 | Records the liability owed to the affiliate |
The journal entry reference includes the commission record number and affiliate name. When the payout is processed, create a manual payment entry in Accounting to debit 300201 and credit your bank account.
You can change the accounts any time in Settings → MLM Affiliate → Accounting. The new accounts will apply to future commissions. Existing journal entries are not affected.
Affiliate Portal
Affiliates access their dashboard at /my/affiliate after logging into the website portal.
https://yourstore.com/ref/AB12CD34
Referral Links & Tracking
Each affiliate has a unique 8-character referral code (e.g. AB12CD34). When a visitor arrives via the referral link, a cookie (mlm_ref) is set in their browser. When they confirm a sale order, the system reads the cookie and assigns the referrer.
How referral attribution works
Visitor clicks referral link
yourstore.com/ref/AB12CD34 → redirected to the shop homepage. A cookie mlm_ref=AB12CD34 is set with a 30-day expiry.
Visitor adds to cart and proceeds
On each cart update, the system reads the cookie and sets referrer_partner_id on the sale order.
Order confirmed
Commissions are generated for all eligible products in the order.
Affiliates can view and download a QR code version of their referral link from the portal — useful for in-person events, printed materials, and social media.
Affiliate Wallet
The wallet is a virtual credit balance. Approved wallet commissions accumulate here. Affiliates can spend their wallet balance at checkout or request a cash payout.
Wallet balance calculation
− Paid wallet commissions
− Amount used in active orders
Spending wallet at checkout
On the checkout page, affiliates see a "Use Wallet Balance" option. Selecting it adds a negative-value line item to the order equal to the amount used, reducing the total payable.
The wallet discount line has special handling to prevent Odoo's price recomputation from resetting it to $0. Do not manually modify this line in the sale order form — use the portal checkout flow instead.
Requesting a Payout (Affiliate)
Affiliates submit payout requests from the portal at /my/affiliate/payout/new.
Commission Engine Reference
L1 split logic
If the buyer has an upline partner (was referred by someone), and the current referrer is different from the buyer's upline, the Level 1 commission is split 50/50 between the two. This prevents commission conflicts when both a referral link and an upline relationship exist.
Normal L1 share: $60 (60% of $100 pot)
Split result:
Bob receives → $30 (half, from referral link)
Alice receives → $30 (half, as buyer's upline)
Self-referral prevention
If the referrer is the same as the buyer (referrer.id == buyer.id), no commissions are generated for that order. This check runs inside the commission engine before any records are created.
Commission engine processing order
Order confirmed
sale.order.action_confirm() triggers _generate_mlm_commissions().
Per order line: find rule
find_rule_for_product(product, pricelist) searches the 6-tier priority chain and returns the best matching commission rule.
Calculate commission pot
rule.compute_total_commission(price_subtotal, qty) returns the total pot for this line.
Walk the upline chain
Starting from the referrer (or buyer's upline), traverse upline_partner_id links up to max_level deep. Create one commission record per level per line.
Apply multipliers
Each commission amount is multiplied by the recipient's active campaign multiplier × their tier multiplier.
Fraud Protection
| Protection | How it works | Configuration |
|---|---|---|
| Self-referral prevention | No commissions generated if referrer = buyer | Always active, not configurable |
| Application approval | New affiliates must be approved by admin before earning | Settings → Require Application Approval |
| Commission hold period | Commissions locked for N days after creation — cannot approve during return window | Settings → Commission Hold Period (Days) |
| Refund clawback | When a validated credit note is created, all pending/approved commissions on the original order are automatically cancelled | Always active |
| Minimum payout threshold | Commissions below a threshold cannot be marked as Paid | Settings → Minimum Payout Amount |
Email Notifications
| Trigger | Template | Recipients |
|---|---|---|
| Commission approved | email_template_commission_approved | Earning affiliate |
| Commission paid | email_template_commission_paid | Earning affiliate |
| Monthly summary | email_template_monthly_summary | All active affiliates with email |
The monthly summary cron runs on the 1st of each month and sends previous month's totals. It can be disabled in Settings → Send Monthly Summary Emails.
Frequently Asked Questions
The accounts and journal were created but not linked to Settings. Why?
This happens when the module was first installed with the old version that had invalid account codes (MLM-EXP / MLM-PAY with hyphens). The env.ref() lookup fails silently because the XML IDs were never registered. Upgrade to v2.30 (18.0.2.18.0) — the migration script automatically wires up the links on upgrade.
A commission shows "On Hold" and won't approve. Why?
The commission's hold_until date hasn't passed yet. This is determined by the Commission Hold Period in settings. Wait until the hold date, or reduce the hold period in settings (future commissions only). The nightly cron (_cron_release_held_commissions) automatically approves expired holds.
Why did a commission get cancelled automatically?
A credit note (refund) was validated for the original invoice. The refund clawback system cancels all pending/approved commissions linked to the original sale order. This is by design to prevent paying commissions on returned goods.
Can I change the commission accounts after installation?
Yes. Go to Settings → MLM Affiliate → Accounting and change the fields. The new accounts apply to future commissions only. Existing approved journal entries are not affected.
An affiliate isn't getting commissions even though they have a referral link. Why?
Check these in order: (1) Is the affiliate's affiliate_status set to "Approved"? (2) Is the commission hold period preventing approval? (3) Does a commission rule exist for the products in the order? (4) Is the customer the same person as the affiliate (self-referral)? (5) Was the referral cookie set before the order was confirmed?
The wallet balance looks wrong for an affiliate. How is it calculated?
Wallet balance = sum of approved wallet commissions − sum of paid wallet commissions − wallet amounts used in active (non-cancelled) sale orders. Check the affiliate's commission list and filter by payout method = Wallet to verify each component.
Can I use this module with Odoo Community?
Yes. The module depends only on sale_management, account, website_sale, portal, auth_signup, mail, and base_setup — all of which are available in Odoo 18 Community Edition.