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 posted by the run started from the Sales Commission applet, and points by the scheduled membership-points run, and both read the schemes that are active.

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 run started from 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 run. For points, the company’s member-point settings in Organisation (member_point_award_doc_in, member_point_in_doc_status) decide which document type and posting status the scheduled run picks up.
• 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 per unit the commission for that line is 0.

Cash commission (Sales Commission Applet)

The commission posting (the SALES_COMMISSION_POSTING_JOB_PROCESSOR job, or a run from 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.

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.