Commission Scheme

Define how sales commissions and membership points are earned: which sales qualify, and how much each level earns. A scheme never pays anything by itself. Commission is worked out when a sales document is finalised, where your tenant has that follow-on job switched on, or when a cycle is processed in the Sales Commission applet; points come from a scheduled run. Each commission figure is worked out once, from the document and the scheme as they stood at that moment, and stored, so changing either afterwards does not move it. A sale returned or voided later keeps its commission until someone deducts it by hand.

Overview

The Commission Scheme applet is where you define how sales commissions and membership points are earned. A scheme is master data: a set of rules that decide which sales documents qualify (by branch, company, document type, date, customer type, member class, sales agent category, items or item categories) and a treatment that says how much is paid per downline level (a price source, an operator and a value, optionally through a formula or a tiered Pricing Model). Two supporting masters live in the same applet: Sales Groups (named groups of employees) and Pricing Models (range-to-rate tables).

The applet itself never pays anything. Active schemes are read by two backend processes: the sales-commission posting, which runs as a follow-on job of Finalise where your tenant has it switched on and as stage 1 of a cycle in the Sales Commission Applet (cash commission for sales agents and MLM uplines), and the scheduled membership-points run described on the Membership Admin Applet page (points on qualifying bills). A scheme can also be attached to an e-commerce website in CP Commerce Admin and to an MLM program in Membership Admin.

Where it fits

Screens and menus

The applet root route is applet/tnt/wavelet/erp/commission-scheme-applet. The left menu has three listings plus Settings and Personalization.

Rules are added from inside the Edit screen: on a Rules tab, + opens Add Rule - Doc Hdr / Multi Line / Single Line, where a Rule Type dropdown reveals the form for that rule type. Adding a rule, adding filter values to a rule, or editing a treatment only updates the draft in the browser; nothing reaches the server until you click SAVE on the Edit screen (every snackbar ends with “Please save changes”).

Configuration

Before you can use it

• Companies and branches exist in Organisation — needed for Company and Branch rules.
• Employees exist in the Employee Applet with is_employee set: only such entities appear in the Sales Group › Salesman picker, and the Employee Category rule matches the categories (labels from the EMPLOYEE_CATEGORIES list) tagged on the document’s sales agent.
• Items and item categories exist in Inventory Item Maintenance — the Item, Item Category and regex line rules read item_guid, item_code, item_name and the item’s categories from the document line.
• Member classes and labels exist in Membership Admin; a points currency exists in Membership Admin (PTS CCY Module) if the treatment awards points.
• Pricing schemes (maintained outside this applet) exist if a treatment uses the Pricing Scheme price source; the Treatment tab lists the pricing schemes it can find.
• For the money to be paid, the Sales Commission Applet must be installed and its cycle processed: even where Finalise writes the commission lines, only a cycle turns them into a report and a payout. For points, the company’s member-point configuration (MEMBER_POINT: member_point_award_doc_in, member_point_in_doc_status) decides which document type and posting status the scheduled run picks up. It is set through the company API; the Organisation applet does not show it (Points Setup).
• API permissions: TNT_API_COMMISSION_SCHEME_HDR_{READ, CREATE, UPDATE, DELETE, OWNER, ADMIN, MEMBER} (tenant owner/admin bypasses), and the corresponding TNT_API_SALE_COMMISSION_PRICING_MODEL_HDR_* / _LINE_* sets for pricing models. The commission and points runs read schemes on their own and need no user permission.

Applet settings

The applet has its own Field Settings and Default Selection screens; Default Selection saves for the whole tenant. Anyone with access to the applet’s Settings menu can change them.

Only one setting is shown, saved and actually used:

Shown and saved, and used by nothing:

• Default Branch (DEFAULT_BRANCH) and Default Location (DEFAULT_LOCATION) on the same Default Selection screen. They are saved (picking a branch also fills in the branch’s main location), but commission schemes, sales groups and pricing models have no branch or location field, so nothing uses them. RESET clears both.

Not functional:

• Settings › Field Settings shows eight toggles (Unit Discount, SST/VAT/GST, WHT, Blanket Order, Segment, G/L Dimension, Profit Center, Project) and a SAVE button that does nothing. Treat the screen as a placeholder.
• Personalization › Default Selection shows Default Branch / Default Location, but choosing a value fails and SAVE saves nothing.

There are no document-behaviour settings: schemes have no posting status, numbering or printables.

Feature visibility / permissions

No SHOW_* / HIDE_* client-side permission is checked anywhere in the applet, and none is defined for it. Access control is therefore the API permission set listed above plus the shared Feature Visibility screen.

Fields

Commission Scheme — Create and Main Details

On CREATE the effect writes the header with all three rule groups set to Rules Logic AND / Negation DISABLED and one Level 0 treatment whose commission and membership-points price source and operator are NA.

Rules tabs (Doc Hdr, Multi Line, Single Line)

Each tab has two group-level fields and a grid of rules (Rule Name, Rule Type, Negation Logic):

Every rule form carries Rule Name (required, max 255) and its own Negation Logic (inverts that one rule). Each rule type can be added once per tab — a second attempt shows “RuleType already exists. Cannot add rule with same ruleType again” and returns to the tab.

Rules - Doc Hdr (document-level; rule types in the dropdown):

A Company, Branch, Member Class, Member Label, Sales Group or Employee Category rule saved with an empty pick list passes unconditionally (the negation is not applied either).

Rules - Multi Line and Rules - Single Line (item-level; same dropdown):

Only lines with transaction type PNS (product and service lines) are considered. Multi Line is evaluated on the whole document: the matching lines are collected, then their summed quantity_base must be ≥ Min Quantity and summed amount_txn ≥ Min Amount (no matching line → rule fails). Single Line is evaluated per line during treatment: each line must individually match and meet both minimums, and only matching lines earn commission or points.

Treatment tab

One block per level; Level 0 (Self) always exists, Add Uplines appends Level 1 (Parent), Level 2 … up to 10 levels (MAX_DOWNLINE); the last level can be deleted.

Sales Group

A sales group also has a Sales Group Name (required) and a free-text Description.

Pricing Model

The line form enforces “Please enter one of the following fields: Commission Value or Membership Point Value”.

Lifecycle and effects

Commission schemes, sales groups and pricing models are master data: no posting status, no journal, no stock. DELETE does not check whether websites, MLM programs or existing commission reports still use the scheme.

How a scheme is evaluated

1. Load every scheme with status ACTIVE.
2. For each scheme, each rule group is checked. Doc Hdr and Multi Line groups are evaluated against the whole document and both must pass. Inside a group the rule results are combined with AND or OR and then the group’s negation is applied; an empty group passes.
3. If the scheme has Single Line rules, the treatment is computed line by line (only PNS lines) and summed; otherwise it is computed once on the document.
4. A scheme is kept for cash commission only if at least one level has a commission price source other than NA and an operator other than NA.

How the treatment amount is computed

• Price source: header amounts are the document’s standard, net, transaction or open-balance amount; line amounts and Base Quantity are summed over the goods lines (or the single line); Price Unit Cost = Σ moving-average cost price × base quantity; Pricing Scheme = the item’s sales unit price in the chosen scheme × base quantity.
• Operator: MULTIPLY = source × value; ABSOLUTE = value; ADD / SUBTRACT = source ± value; FORMULA = the expression evaluated with {PRICE_SOURCE} replaced by the source (or, for receipt vouchers, the contra amount) and {DAY} by the days between the invoice date and the receipt’s contra date (0 when there is no contra) — a parse error or a negative result yields 0; NA = 0.
• PRICING MODEL is not applied when a document is evaluated (it gives 0 there). It is applied only to the intermediate lines of a commission cycle (create full commission in the Sales Commission Applet): the first band that contains the summed source value is used — its commission multiplier when non-zero, otherwise its commission value.
• Below Cost unchecked: for line-level commission, if the price-source value is lower than the line’s moving-average cost divided by the line’s quantity, the commission for that line is 0 (see the Treatment tab row for what that does to a multi-unit line).

Cash commission (Sales Commission Applet)

The commission posting (the SALES_COMMISSION_POSTING_JOB_PROCESSOR job, which runs after Finalise where your tenant has switched it on and has no clock of its own, or stage 1 of a cycle in the Sales Commission Applet) loads the document, refuses it if its commission has already been posted, finds the matching schemes with a usable treatment, and writes one intermediate commission line per scheme (per line when Single Line rules or MLM are involved). Then it marks the document’s commission as posted. Details that matter for scheme design:

• SALES_AGENT schemes use the Level 0 treatment for the document’s sales agent.
• MLM schemes look up the customer’s MLM lineage: each upline at level n receives the Level n treatment, computed per line.
• A Receipt Voucher earns commission only through its contra links to invoices; an RV with no contra produces nothing. This is the path where {DAY} in a formula is meaningful.

Membership points (scheduled)

The scheduled job MEMBERSHIP_POINTS_COMMISSION_QUEUE_PROCESSOR (schedule it in the Scheduler) selects documents of the type and status the company’s member-point settings name, whose points commission has not yet been posted, evaluates the rules (treatment presence is not checked) and applies only the first treatment’s Membership Points block (“Supports only 1 treatment”), creating a membership-points commission report valid from the transaction date to the transaction date + Validity Period. The same number can be previewed for one document through the API.

Where a commission figure comes from

Every number on a commission report is a sum of stored commission lines, and each line is a snapshot taken at the time of one posting:

Three things follow from that:

• A rate change is not retroactive. Raise a scheme from 2% to 3% on the 10th and every line written before the 10th keeps 2%. The document is already marked, so no later run reads it again.
• Every matching active scheme pays. A store-wide 1% scheme and a 2% smartphone scheme that both match the same line both write a line for it, and the agent earns 3%. Nothing picks the better one, so keep schemes from overlapping unless stacking is what you mean.
• Cost-based settings read the cost the line carried when the commission was written. Costing reaches the document line in a later step of the Finalise chain, and Finalise queues the commission job alongside the other follow-on jobs rather than after costing. Where commission is written at Finalise, Below Cost and the Price Unit Cost source can therefore read a line whose cost has not arrived yet; a cycle processed days later reads the cost that has since been written.

Worked example: 2% on smartphones at GS-KV-01, and a return three weeks later

GadgetSphere pays its sales staff at branch GS-KV-01 2% on flagship smartphones and 5% on accessories, settled monthly. A scheme has one rate per level, so this is two schemes:

On 3 March you sell a flagship smartphone at RM 4,200 and wireless earbuds at RM 300 on one sales invoice, with yourself as the sales agent (leave tax aside). When the commission is written, at Finalise or at the March cycle’s stage 1, each scheme passes the header rules and writes a line for the item line its category rule matches: RM 84 on the phone and RM 15 on the earbuds. The March report shows RM 99, and its Line Item tab shows both rows with the scheme beside each.

On 24 March the customer brings the phone back and a sales return is raised against the invoice. The commission does not move. A cycle reads only sales orders, sales invoices, cash bills and knocked-off receipts, and the Document Type rule has no box for a return; the RM 84 line was stored on 3 March and nothing removes or offsets it. The March report still says RM 99, and whoever approves the payout deducts RM 84 on the payment voucher, as the Sales Commission page describes. Had the return come in April, after March was paid, the deduction belongs to April’s payout, and the April report does not mention it either.

That is also why both schemes carry a Document Type rule. Without it, where commission is written at Finalise, the return itself is offered to the schemes like a sale. A return’s lines hold positive amounts and keep their sign in a separate field, and the commission is worked out from the amounts, so the return would add RM 84 instead of taking it back. This is read from the code and has not been seen in tenant data; the Document Type rule prevents it either way.

If the invoice is voided instead, timing decides. Voided before any commission was written, it earns nothing, because only finalised documents are read. Voided after, its lines stay, and stage 3 and REGENERATE still count them, because they select lines by date, not by the document’s state. Whether a return or a void should reduce commission automatically is a policy question still open with BigLedger; today the deduction is a person’s job, done at payout.

Verify a scheme on one invoice before the cycle closes

A scheme can be wrong in ways the Edit screen will never show, so test it on a real document before the first payout:

1. Pick one finalised sales invoice from the current period that the scheme should match, at the branch it names, with at least one item each rule should catch.
2. In the Sales Commission applet, run the cycle’s three stages in order. Stage 3 replaces the cycle’s reports, which is harmless before a payout is raised.
3. Open the agent’s report and its Line Item tab. Expect one row per matching item line, naming the scheme you meant, with Money equal to the rate times the line amount: RM 84 and RM 15 in the example.

Other references

• CP Commerce Admin › Website › Commission Scheme links a website to a scheme.
• Membership Admin MLM programs carry a commission scheme.

Related applets

• Sales Commission Applet — runs the posting that reads active schemes and produces commission transaction lines, reports and payouts; the only place a Pricing Model treatment produces a number.
• Membership Admin Applet — member classes and labels used by header rules, MLM lineage used by MLM schemes, MLM programs that reference a scheme, and the company member-point settings that drive the points run.
• MLM Admin Applet — the programs and lineage an MLM scheme walks; the points currency picked on the Membership Points treatment is defined in Membership Admin (PTS CCY Module).
• CP Commerce Admin — links a scheme to a website.
• Sales Invoice (Internal), POS General, Sales Order (Internal), Receipt Voucher (Internal) — the document types a scheme can match; the invoice’s sales agent field is the agent paid.
• Employee, Customer, Organisation, Inventory Item Maintenance — the masters the rules pick from.

Troubleshooting

Related documentation

• Membership module — core concepts and the MLM use case.
• Sales Commission Applet — commission reports and payouts.
• Membership Admin Applet — member classes, labels, MLM lineage and the points run.