Programme settings
Every control on Admin → Affiliate → Settings — the structure selector, level percentages, approval switch, commission ceiling, payout threshold and reward payout token — 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 controls can stop the entire programme
paying without producing a single error message, and the reward payout controls
decide what every reward is paid in.
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
- Pick the structure: DIRECT, BINARY or UNILEVEL
- The level count, between 2 and 7
- Enter each level's share of the commission
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.
The threshold is in US dollars. Each unclaimed reward is valued at its own currency's price and the values are added, so 100 USDT and 2,000 PBX at $0.05 count as $200. If one of the member's reward currencies has no price at all, the claim is allowed rather than blocked, and the backend log says which currency could not be valued.
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.
Before Core 6.8.6 the comparison was a plain number against the raw sum of unclaimed rewards, whatever currencies they were in.
Reward Payout
These four controls decide what rewards are paid in. Each condition still decides what a reward is worth: its percentage or fixed amount, in its own currency. Saving any of them needs a Super Admin, because they decide how many tokens every affiliate is paid.
- Each condition's own currency (
CONDITION) — the behaviour before this setting existed. A reward is paid in its condition's wallet type and currency. - One ecosystem token (
TOKEN) — every new reward is paid in the Reward Token below, into the affiliate's ECO wallet. The condition's value is converted into the token at the token price when the reward is earned. Example: a deposit condition paying 5% in USDT, a 1,000 USDT deposit, and PBX at $0.05 earn the referrer 50 USDT worth, paid as 1,000 PBX. A fixed 10 USDT reward pays 200 PBX. Level splits under BINARY and UNILEVEL apply before the conversion.
Choosing token mode without saving a token changes nothing: rewards keep paying in each condition's currency, the screen warns you, and the backend logs it once.
A list of the active ecosystem tokens, one entry per code, with the chains each exists on. The reward lands in the member's ECO wallet for that code, which the claim creates if they do not have one. The save is refused if the code is not an active ecosystem token. Token payouts need the Ecosystem extension enabled.
The token's price also values any condition that names this token as its own currency, in either mode. Before Core 6.8.6, a percentage condition paying an ecosystem token could not be valued and paid nothing.
Below the list, the screen shows the token's current market price, the fixed price, and the price rewards convert at right now, for the saved settings.
- Fixed price (
FIXED) — the USD price below. It cannot be moved by trading. This is the default: until you enter a price, rewards in the token are held, not paid. - Market price (
MARKET) — the last trade on the token's ecosystem market against USDT (for PBX, the PBX/USDT market). A market that has never traded has no price. - Market, or fixed when there is no market (
MARKET_OR_FIXED).
With market pricing, a few trades on a quiet token market change how many tokens every reward pays: a lower price pays more tokens. If your token's market is thin, use a fixed price, or the market with a fixed fallback and watch the book.
A reward worth $10 pays 10 divided by this many tokens. Type it carefully: a price of 0.0001 instead of 0.1 pays a thousand times the tokens intended. It must be a positive number.
When the token has no usable price — market pricing and no trades yet, or a fixed source with no fixed price — rewards in the token are not written, rather than written in the wrong unit. The event-driven engine logs and skips the reward; the hourly job holds it and pays it on the first run that has a price while the period is still being looked at again: the current period and the one before it, about two days on a daily condition. Event-driven rewards for activity in that window are lost, because nothing retries them.
Rewards already earned never change currency. Every reward records the currency it was earned in. Switching the mode, the token or a condition's currency affects new rewards only. A reward earned in USDT is claimed in USDT after you switch to PBX, and a PBX reward stays PBX if you switch back.
When a member claims a token reward, the platform loss is booked in the token against the treasury's ECO wallet for it. Make sure the platform holds enough of the token on chain to cover what members can withdraw.
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.