MLM Admin Applet

Run a member-gets-member referral programme: a program with a start and end date, members enrolled as participants, and the lineage of who introduced whom, up to ten levels deep, filled by invitation or by a participant’s QR link. The applet records the tree and pays nobody — the money is an MLM-type scheme in Commission Scheme, and the commission run uses the cycle’s scheme, not the one named on the program. Take the scheme design to the company’s legal adviser before the first invitation is sent; nothing here distinguishes paying on sales from paying on recruitment.

Overview

The MLM Admin applet is where you run a member-gets-member referral programme. You create a program (a referral campaign with a start and end date), enrol members from Membership Admin as participants, and the applet keeps the lineage — who introduced whom, one upline-to-downline link at a time, up to ten levels deep. New downlines arrive by invitation (an e-mail, SMS or WhatsApp message sent through a contact-centre channel, accepted on a registration page) or by scanning a participant’s QR link, which drops them onto your storefront’s sign-up page with the inviter’s key attached.

The applet records the tree. It pays nobody: the money is an MLM-type scheme in Commission Scheme, and the Sales Commission posting run walks the lineage up from the buyer and writes one commission line per upline level.

Where it fits

Screens and menus

Route root: applets/wavelet/erp/mlm-admin-applet/. Opening the applet lands on Invitations.

Program Create has a single Details tab. Program Edit has five tabs and a Delete button:

The participant’s QR Code tab renders the participant’s personal invitation link as a QR image, a copyable link and a PNG download — the self-service invitation link described under Lifecycle.

Settings and Personalization menus

Configuration

Before you can use it

Applet settings

Settings live in an applet-local settings container (not the shared field-configuration component); there is no applet-settings model file in this project. Tenant administrators can open the screens; nothing they save is read.

Model-only keys: none — the project has no settings model. Keys read at runtime without a declaration: none found.

Document behaviour settings

Not applicable — no documents.

Feature visibility / permissions

API permissions are the TNT_API_DM_MLM_* family (OWNER, ADMIN, MEMBER, CREATE, UPDATE, DELETE, READ for each of programs, participants, lineages, invitations, entity contacts and endpoint links) plus TNT_API_DM_MLM_REGISTRATION_{OWNER, ADMIN}. Accepting an invitation and following a QR link need no sign-in, by design: they are used by people who are not yet users.

No menu is restricted, and the applet has no client-side permissions of its own.

Fields

Program

Participant — the form also carries Program (read-only) and Object Type, which offers MEMBERSHIP only.

Lineage — the form also carries Lineage Type, a label nothing that pays commission reads: the form sends Membership, and the lineage job copies the invitation’s own type (MEMBERSHIP, ENTITY or ENTITY_CONTACT).

Invitation

Entity Contact

Communication Endpoint Link

Lifecycle and effects

Nothing posts, nothing moves. No record in this applet is a document: there is no journal, no stock movement, nothing for VOID to reverse. Every record is simply ACTIVE or INACTIVE.

How a downline joins — two paths

    stateDiagram-v2
    [*] --> CREATED: invitation saved in the applet
    CREATED --> SENT: the invitation-sending job sends via the program's endpoint links
    SENT --> ACCEPTED: invitee registers through the invitation link
    [*] --> ACCEPTED: QR / storefront sign-up with the inviter's key (SELF_CLICKED)
    ACCEPTED --> LINEAGE_UPDATED: the lineage job writes the lineage row
    LINEAGE_UPDATED --> [*]
    note right of CREATED
        REJECTED and EXPIRED exist as statuses
        but nothing sets them automatically
    end note
  

Path 1 — an invitation sent by the applet. You create an invitation for one or more invitees, with Invite Status Created. The scheduled job MLM_INVITATION_LINK_PROCESSOR picks every ACTIVE invitation whose Invite Status is CREATED and reads the program’s ACTIVE endpoint link, whose code names the channel. The endpoint it sends from and the contact-centre template it uses are not taken from the link: both are set in the scheduled job’s own settings, one pair per channel. The template’s <URL-KEY> is replaced by the program’s URL Forward resolved for the inviter, the inviter’s entity e-mail is copied in, and the message goes by SMS (needs an invitee phone), e-mail (needs an invitee e-mail) or WhatsApp. On a 2xx reply the status becomes SENT. There is no fallback: a program with two or more ACTIVE links fails the run before anything is sent, and a send that fails — an e-mail link with an invitee who has only a phone, say — stops the run at that invitation, which stays CREATED and is tried again on the next run until someone fixes it or sets it INACTIVE. Whoever owns the programme checks the Invitations listing after each run: anything still at CREATED has not gone. The invitee opens the link and registers — first and last name, e-mail or phone, a password and a referral source — without needing to sign in. If no confirmed login exists for that e-mail or phone, a new login is created and a six-digit code is e-mailed or texted, valid for eight hours, which the invitee enters with their password to finish. With or without that step, the platform finds or creates the customer entity, finds or creates the membership card, creates the participant, and sets the matching invitation — same inviter and program, same e-mail or phone — to ACCEPTED with the child member and entity filled in. No match raises NO INVITATION CONTAINER COULD BE FOUND.

Path 2 — a QR or shared link. Each participant’s QR tab carries a personal link that needs no sign-in. It redirects to the program’s URL Forward with <URL-KEY> replaced by the participant’s key, or fails with not found when the URL Forward lacks the placeholder or is not a valid URL. When the visitor registers on the storefront with that key, the registration looks the inviter up, creates the new user’s entity, membership card and participant with referral source INVITE, and writes an invitation that is already ACCEPTED, type SELF_CLICKED, lineage type MEMBERSHIP. A website set to enforce MLM for every registration turns a missing key into a hard error that refuses the registration.

Both paths end the same way. The scheduled job INVITATION_INSERTION_INTO_LINEAGE_PROCESSOR takes every ACTIVE invitation at ACCEPTED that carries a child member and entity and a parent participant, member and entity, requires the child to already be a participant (it fails otherwise), creates the lineage row — computing its level — and sets the invitation to LINEAGE_UPDATED.

Lineage maintenance. Changing a row’s upline re-levels its whole subtree; deleting a row re-levels the descendants. Membership Admin’s MLM tab shows the chain each way.

Where the money is. The sales-commission posting run reads the lineage only for a scheme whose Commission Type is MLM: it loads the buyer entity’s participants, walks the lineage upward level by level (level 0 is the buyer, then each parent), and writes one intermediate commission line per upline per sales line with the program, level, member and upline entity, skipping levels whose treatment is zero. The scheme applied is the one the commission cycle selects; the program’s own Commission Scheme field is not consulted — the report uses the program only to print its name. The member’s referral code on the membership card is a separate mechanism that MLM does not use.

Every record in this applet can also be read and written through the API, and a signed-in user can enrol themselves in a program and list their own participations — see the developer documentation.

Check that the scheme you are building is lawful, because nothing here will

This applet will happily build a tree ten levels deep and pay every level of it, and it makes no distinction between a scheme that pays on sales and a scheme that pays on recruitment. That distinction is the one a regulator cares about, and in Malaysia a direct-selling or multi-level scheme is licensed rather than merely registered. The commission run reads the lineage and the scheme’s per-level treatments and asks nothing else.

So there is one question the software cannot answer and will never raise: what is the upline actually being paid for? If the treatment at each level is driven by a downline’s sales, the tree is a commission structure. If it is driven by the act of recruiting — a payment that exists whether or not the new participant ever buys anything — it is a different thing in law, and no configuration on this screen makes it safe.

Who and when: whoever owns the programme takes the scheme design to the company’s legal adviser before the first invitation is sent, not after the tree exists — because a lineage is easy to build and hard to unwind, and the participants in it are customers. The evidence they need is small: the Commission Scheme’s per-level treatments, what each treatment is calculated on, and the maximum depth. They know the review is finished when they can say, for each level, which sale the payment came from.

Related applets

• Membership Admin — participants are its membership cards; its member edit screen’s MLM and Referrals tabs show the tree this applet builds.
• Commission Scheme — the MLM commission type and its per-level treatments (up to ten uplines) are defined there.
• Sales Commission — the posting run that walks the lineage and the report that shows MLM Program and MLM Member per line.
• Customer Maintenance and Entity — the entities behind participants and entity contacts; acceptance creates a customer entity when none exists.
• Unified Contact Center — the e-mail, SMS and WhatsApp endpoints and message templates the invitation processor sends through.
• CP Commerce Admin — the storefront whose sign-up completes the QR path and whose post-registration settings can make the inviter key mandatory.

Troubleshooting

Related documentation

• Membership module
• Membership applets
• Commission Scheme — the MLM commission type
• Integrate an external system — headers for the MLM API