Programme settings
Every control on Admin → Affiliate → Settings — the structure selector, level percentages, approval switch, commission ceiling and payout threshold — what each one really does and what breaks when it is wrong.
Admin → Affiliate → Settings (/admin/affiliate/settings) is a short screen
with a large blast radius. Two of its five controls can stop the entire
programme paying without producing a single error message.
The screen needs the access.affiliate.settings permission. It saves through
the platform settings endpoint, so changes take effect for every process as soon
as the settings cache invalidates — no restart.
General tab
Require Approval
Off, a referral is ACTIVE the moment somebody registers through a link and
starts earning immediately. On, it is created PENDING, it is held out of the
tree, and neither reward engine will look at it until you approve it on
Admin → Affiliate → Referrals.
Turn it on if you need to vet affiliates for fraud or compliance. Be aware that you are now committing to working a queue: a referral left pending indefinitely earns nothing, and the referred user's activity in the meantime is gone — there is no back-payment when you approve late.
The referral's placement in a binary or unilevel tree happens at approval, not at registration, so a pending application never occupies a tree slot it might not deserve.
MLM Configuration
Three settings behind one custom control.
Picking BINARY or UNILEVEL reveals a level count and one percentage box per
level, stored as affiliateBinaryLevel1 … affiliateBinaryLevel7 and
affiliateUnilevelLevel1 … affiliateUnilevelLevel7.
The percentages are shares of the commission, not extra commission. With a 2% deposit condition and levels of 50 / 30 / 20, a 1,000 USDT deposit produces 20 USDT of commission split 10 / 6 / 4 — never 2% three times over.
If the level percentages total more than 100%, the engine logs an error and returns without creating a single reward — not just for the excess level, for the whole transaction. Every commission on the platform stops, and the only sign is a line in the backend log.
The screen shows a running total and turns it red for exactly this reason. Check it before you save.
Two more things the screen tells you and it is worth repeating:
- A level with no percentage is skipped, not defaulted. Set the count to 5 and fill in three boxes and levels 4 and 5 earn nothing.
- Under
BINARY, "Level 1..N" means levels of the sponsor chain, not depths of the binary tree. Binary placement and spillover change the diagram, not the payees. See Referral structures.
DIRECT needs no levels and no percentages: the immediate sponsor gets the
condition's full reward.
Commission tab
Maximum Commission Rate
A real limit, enforced server-side. Saving a PERCENTAGE condition above it is
rejected with a message quoting both the attempted rate and the ceiling. Raise
this first if you genuinely want a higher rate.
It does not constrain FIXED rewards — an absolute amount is not a
percentage — so a fixed reward of 10,000 saves happily under a 30% ceiling.
Nothing caps those; review them by hand.
It also caps one condition at a time, not the combined cost of several conditions collecting on the same activity. Four active rules of 25% each pass the ceiling individually and cost you 100%. The conditions screen surfaces that as an effective percentage rate; see Commission conditions.
Payout Threshold
Enforced at claim time against the member's total unclaimed balance, not against the individual reward. Once they are over the line they can claim rewards one at a time, including ones smaller than the threshold. Below the line, the error names both figures.
Set it to 0 to disable it entirely.
There is no partial payout, no scheduled sweep and no expiry. A member with 4 USDT of unclaimed commission under a threshold of 50 simply never gets paid, and the amount sits on your books forever as a liability that never appears in profit reporting.
If your rates are fractions of a percent on small transactions, keep the threshold low. The default of 50 assumes reward amounts an order of magnitude larger than a 0.1% spot-trade commission produces.
The units are whatever the conditions pay in — the field is labelled with a dollar sign, but the comparison is a plain number against the sum of unclaimed rewards. On a default install those are USDT.
What is not on this screen
Things operators reasonably expect to find here and will not:
- A default commission rate. There used to be one; nothing read it, because commissions come from the per-condition reward and there is no per-affiliate rate in the schema for a default to apply to. Rates live on Admin → Affiliate → Conditions.
- Cookie or attribution window. There is none. A referral link is stored in the browser's session storage and credited if the visitor registers in that tab session; close the tab and the attribution is gone. Nothing is configurable about it.
- Payout schedule or auto-payout. Every payout is pulled by the member pressing Claim. There is no scheduled disbursement.
- Per-affiliate overrides. Every member is on the same rates. To pay somebody more, create a reward by hand.
- Fraud thresholds or geo rules. Self-referral is blocked and referral cycles are detected, and that is the extent of the built-in controls.
- Evaluation period. A condition's
DAILY/WEEKLY/MONTHLYwindow is a column no endpoint exposes. Everything sits onDAILYunless changed in the database.
Legacy configuration
Installs upgraded from an older release may still carry two older keys:
mlmSystem (the structure) and mlmSettings (a single JSON blob holding both
level configurations). They are read as a fallback when the current keys are
absent, so an old install keeps working untouched.
The moment you open and save this screen, the current keys win. If you are migrating an old install, open the settings screen once and save deliberately — that converts the configuration to the form every other screen reads, and lets you see the level total before it matters.
Related: Roles and permissions for who can open this screen, and API and data model for the tables these settings drive.