A trade scheme in xMatix is a promotional offer — "buy 10, get 1 free", "5% off orders over 50,000" — defined once and applied to documents by the scheme engine. A Scheme carries Scheme Slabs; each slab has Scheme Conditions (what the document must contain) and Scheme Benefits (what the customer gets). The engine evaluates slabs against orders, invoices, credit notes, purchase orders, bills and service orders, applies the qualifying ones, recommends near-misses ("so much more to qualify"), records every application in the Scheme Ledger and enforces budgets and apply-count caps against that ledger live.
Schemes are records of the Scheme entity. In the first-party configuration they belong to the Rewards app; open Schemes there (or from any app that lists the entity). Building and approving schemes is an administrator task; order entry only consumes them.
Find the scheme
- 1
The view switcher: All Approved Schemes hides Draft, Pending Approval and Deactivated schemes, which the engine ignores anyway.
- 2
Scheme Type: Per Sale Order, Per Sale Invoice, Per Sale Order And Invoice, the purchase-side types, or a Per Period variant.
- 3
Application: Auto Apply runs inside the document save; Apply On Selection waits for Apply Scheme on the document.
- 4
Partner Account, Branch and Account scope the scheme; a blank Account means any customer of that company.
- 5
Val From and Val To must cover the document date or the scheme is skipped.
- 6
New creates a Draft scheme header; slabs, conditions and benefits are added from the saved record.
Use the All Approved Schemes view to compare name, Scheme Type, Application, partner and branch scope and validity before opening a record. Only schemes with Status Approved inside their Val From / Val To window are eligible, so this list is the fastest place to distinguish a setup problem from a document-qualification problem.
Read the scheme record
- 1
Status stepper: only Approved schemes are evaluated; Deactivated retires one without deleting it.
- 2
Scheme Name and Scheme Type; the type decides which document (or accumulated period) the slabs are tested against.
- 3
Sequence Number orders schemes for evaluation, lowest first.
- 4
Application: Auto Apply or Apply On Selection.
- 5
Multiple Fulfilment Treatment decides what happens when several slabs qualify at once: all, first or last fulfilled.
- 6
Eligible Partners (partner account, partner account group, branch) and Eligible Accounts (account, account group) scope who gets the offer.
Details is the header. Read it before the child tabs, because it decides whether the engine considers any slab at all:
| Field | What it does |
|---|---|
| Scheme Type | Which document the scheme evaluates: Per Sale Order, Per Sale Invoice, Per Sale Order And Invoice, Per Purchase Order, Per Bill, Per Purchase Order And Bill, Per Repair Order, Per Repair Order And Invoice — or a Per Period variant that qualifies on totals accumulated over a scheme period rather than one document |
| Application | Auto Apply runs inside the document save; Apply On Selection only surfaces in qualification and recommendation lists and takes effect when a user runs Apply Scheme |
| Status | Draft, Pending Approval, Approved, Deactivated. Only Approved is evaluated |
| Val From / Val To | Validity window tested against the document date; Val To must be later than Val From |
| Sequence Number | Order in which schemes are evaluated, lowest first |
| Multiple Fulfilment Treatment | When several slabs qualify on one document: Apply All Fulfilled, Apply First Fulfilled or Apply Last Fulfilled |
| Period Type, Period Start / End Date | For Per Period types: the accrual buckets; scheme periods are generated when the scheme is inserted |
| Eligible Partners / Eligible Accounts | Partner account, partner account group, branch, account and account group scope; an account group of type Exclude Scheme keeps accounts out |
| Applicable Transaction Type | When set, the document's transaction type must equal it |
| Val Count | Cap on how many distinct documents per customer the scheme may apply to, counted live from the ledger; empty or zero means unlimited |
| Ignore Budget | Skips every budget gate for this scheme |
| Round Off Type | Floor or Ceil applied to computed scheme values such as derived free-item quantities |
| Is Claimable, Claimable Percentage, Claim Generation Frequency | The hook that lets scheme payouts be generated as trade claims |
The status stepper is maintained by editing Status; the seeded Submit for Approval button is a plain save with no workflow behind it, so a scheme goes live when someone with rights sets Status to Approved (or when your organization's own approval process does).
Slabs
- 1
Scheme Slab tab: one row per tier of the offer.
- 2
Slab Name is generated; click it to open the slab with its Scheme Condition and Scheme Benefit lists.
- 3
Reward Applicability: All Rewards, Any One With Lowest Value, Any One With Highest Value or Custom Logic.
- 4
Definition Filter Criteria: All Conditions Are Met, Any Condition Is Met, Always (No Criteria) or Custom Logic Is Met.
- 5
New adds another slab; slabs are evaluated in sequence order.
The Scheme Slab tab lists the tiers — "10–49 units" and "50+ units" are two slabs of the same scheme. Each slab carries a Sequence Number, a Definition Filter Criteria (how its conditions combine: All Conditions Are Met, Any Condition Is Met, Always (No Criteria) or Custom Logic Is Met with an expression such as {1} AND ({2} OR {3}) over condition ordinals) and a Reward Applicability (which qualifying benefits are granted: All Rewards, Any One With Lowest Value, Any One With Highest Value or Custom Logic over benefit ordinals). Slabs are evaluated in absolute-sequence then sequence order. Use Lower Ratio for Rewards makes a multi-condition slab use the lowest qualification count across its conditions instead of the highest.
Open a slab to see its Scheme Condition and Scheme Benefit lists. The Related tab of the scheme itself hosts the same slabs as expandable cards plus an Add Scheme Slab builder that creates slab, condition and benefit rows directly; the seeded Create Scheme Slab, Create Scheme Condition and Create Scheme Benefit buttons have no server handler and do nothing beyond saving.
Conditions
A condition is a type, an operator and a threshold:
| Condition type | Measures |
|---|---|
| Quantity / Value / Value With Tax | The whole document |
| Item Quantity / Item Value / Item Value With Tax | The item in Item (optionally one SKU or lot type) |
| Item Group Quantity / Value / Value With Tax | Items belonging to Item Group |
| Unique Item Count | Distinct items on the document |
Operators are Equal, Does Not Equal, Greater Than, Greater Than Or Equal, Less Than and Less Than Or Equal; quantity types read Condition Quantity, value types read Condition Value. For the two Greater Than operators the engine also derives a qualification count — the whole number of times the threshold was reached — which drives repeatable rewards. Exclude Item Group carves items out of the measure, Exclude Account Group carves customers out, and Use In Ratio Calculation marks the condition whose target-to-achievement ratio feeds ratio-based repeats. Per Period schemes measure the same types over the accumulated period totals.
Benefits
| Reward type | Gives |
|---|---|
| Line Level Discount Percentage / Line Level Discount Amount | A discount on the qualifying lines |
| Discounted Item / Discounted Item Group | Free or discounted units of Discounted Item (or picked from Discounted Item Group), Discounted Item Quantity per qualification |
| Reward Points | Loyalty points stamped on the document lines and mirrored into the ledger |
Free-item benefits either discount matching existing lines or insert new lines flagged as scheme-generated. Repeat Reward grants the benefit once per qualification count; Repeat Rewards In Ratio scales it by the achievement ratio instead and takes precedence. Exclude Qualifying Items forces the reward onto lines other than the ones that qualified, Discounted Item Ranking picks candidate lines High To Low or Low To High by value, Exclude Discounted Item Group keeps a group of items from ever being the rewarded line, Limit Expiry Days is copied onto the rewarded lines as a validity horizon, and Recommendation Text is the marketing copy shown with recommendations.
Budgets and periods
The Scheme Budget tab holds Scheme Account Budget rows in currency. A row with neither partner account nor partner account group is the scheme-wide budget; a row with one of them caps spend for that partner or group. Their displayed Utilized Amount and Budget Available are refreshed from the ledger for reading only; enforcement sums live ledger consumption. A platform validation ("Scheme Budget Exceeded!") blocks a save that would take available budget negative unless the scheme ignores budget. The Period tab lists the Scheme Period rows generated for Per Period schemes (Date From, Date To, Status); a per-document scheme has none.
The Recommendations tab of the scheme layout shows fixed illustrative cards that are not driven by the open scheme. Do not read them as qualification evidence; run Get Scheme Recommendations on the order or invoice instead, which computes the live gap from the document's own lines.
Working with schemes on an order
- Saving the order (inserting, changing or deleting a line) runs every Auto Apply scheme: qualifying discounts land on the lines and free-item benefits add scheme-generated lines, refreshed or removed as the order changes. Skip Scheme on the order suppresses evaluation.
- Get Qualified Scheme Slabs lists the slabs the document currently qualifies for; Get Qualified Benefits lists the benefits available for a set of item groups.
- Apply Scheme commits a chosen slab (and, for slabs with alternative benefits, the chosen benefit or custom-logic group). Apply On Selection schemes only ever apply this way.
- Get Scheme Recommendations returns, per item or for the whole document, the schemes in reach with how much more is needed — e.g. "5 more value required!" — so a rep can nudge the basket to the next slab.
- Reset Scheme removes applied schemes from the document: scheme discounts are cleared, scheme-generated lines deleted and the document's ledger rows removed, which releases its budget consumption.
The same actions exist on invoices and on the purchase and service documents covered by the scheme types.
The ledger and budget enforcement
Every applied benefit is a Scheme Ledger row — one per document line — mirrored from the line state on every save (rows for lines that no longer carry a scheme are deleted). The ledger is the source of record: Val Count limits, scheme-wide and partner budgets and the denormalized utilisation displays are all computed from it. Its Net Scheme Discount is the normalized currency value of the benefit (the discount amount, or line amount times discount percent), and Claimed marks rows a claim has already consumed.
Budget gating works like this:
- A positive legacy header Scheme Budget counts as a scheme-wide cap; the engine compares against the greater of the stored utilised amount and the live ledger sum, so a stale figure cannot wrongly admit a scheme.
- On a sale order a currency benefit can apply even when no budget rows exist; any configured applicable cap still has to have room.
- On a sale invoice, unless Ignore Budget is on, the scheme must have both a scheme-wide budget row and an applicable partner or partner-group row. A missing tier suppresses the scheme on the invoice and removes a copied order discount rather than letting it pass unbudgeted.
- Reward Points do not consume a currency budget. Carts evaluate schemes without writing consumption; committed documents write ledger rows.
Common questions
Why didn't a scheme apply to my order?
Work down this list: Status must be Approved and the document date inside Val From / Val To; the Scheme Type must cover this document (a Per Sale Invoice scheme never fires on an order); an Apply On Selection scheme must be applied by hand; the slab's conditions must actually be met — Get Qualified Scheme Slabs shows what qualifies and Get Scheme Recommendations how far away you are; the account must not sit in an excluded account group, the partner and branch must match, and any Applicable Transaction Type must equal the document's; Val Count must not be exhausted for this customer; and every applicable budget must have headroom. For an invoice, also confirm both budget tiers exist unless Ignore Budget is on. The troubleshooting page has the same list with fixes.
What happens when a scheme's budget runs out?
The engine skips a pending currency benefit when an applicable live budget lacks headroom. Existing benefits on other documents are not clawed back. Resetting the scheme on a document removes that document's effects and ledger consumption. Distinguish exhaustion from incomplete invoice configuration: a missing scheme-wide or partner tier suppresses an invoice scheme even though no displayed budget appears exhausted.
Can a user choose which benefit to take?
Yes, when applying manually: Apply Scheme accepts the chosen slab and, for slabs whose Reward Applicability offers alternatives, the chosen benefit or benefit group. Auto-applied schemes follow the slab's configured applicability instead.
Does resetting a scheme remove the free items?
Yes. Scheme-generated lines are created by the engine and marked as such; Reset Scheme deletes them and clears the scheme discounts from the remaining lines. Their budget consumption is released at the same time.