Short answer: a commission engine should use exact decimal math, never floating point, and every payment it creates should leave a record that explains how it was calculated. Money errors in plan software rarely look dramatic. They show up as a cent that does not add up, a payout that differs from last month's preview, or a distributor who asks why they were paid a certain amount and nobody can say. Exact math and an audit trail are what prevent those problems from turning into disputes.
This article is for founders who will commission plan software and for developers who will build it. It describes design choices we make and why. It does not promise any particular performance figure, and every project depends on the plan and on the scale the client needs.
Why floating point is the wrong tool for money
Most programming languages store ordinary decimal numbers as binary floating point values. Many simple amounts, such as 0.10, cannot be represented exactly in that format. The classic demonstration is that adding 0.1 and 0.2 gives 0.30000000000000004. One such error is invisible. Millions of small calculations, each rounded slightly differently, produce totals that do not match the sum of their parts.
A commission engine multiplies and divides amounts constantly: a percentage of an order, a share of a pool, a currency conversion. The usual fix is to use a decimal type (or whole numbers of the smallest currency unit) with a stated precision, and to round only at defined points. We specify those points in the plan, because the plan is the source of truth. For example: round each commission line to two decimals using round half up, then sum the lines, never the other way around.
Rounding is a business rule, not a detail
Two engines that both use exact decimals can still disagree if one rounds each line and the other rounds the total. Pools shared between many people raise another question: when 100.00 is split three ways, who gets the extra cent? The answer can be arbitrary, but it must be the same every time, and it must be written down. Without a stated rule the result depends on the order in which the database returns rows, and that is not an acceptable basis for paying people.
The same applies to currencies with no minor unit, to currencies that use three decimals, and to conversions. If the plan pays in one currency and members are paid in another, the engine should record the rate used and when it was fixed. Our page on multi-currency and multi-language covers how we handle that.
An append-only ledger instead of a changing balance
A common beginner design keeps a balance column on each member and updates it when a commission is earned or paid. It is simple, and it hides history. If the number is wrong, there is no way to tell how it became wrong.
A better design is a ledger: every movement of money is a new row with an amount, a type, a timestamp, a reference to the thing that caused it, and the identifier of the rule version that calculated it. Rows are never edited or deleted. A mistake is corrected by adding a reversing row and then a correct one. The balance is simply the sum of the rows, and it can be recomputed and checked at any time.
This gives you the property auditors and distributors both care about: for any payment, you can show the order, the rule and the calculation. It also makes reports and reconciliation much easier to trust.
Reproducible runs and idempotent jobs
Commission runs often happen on a schedule: daily, weekly or monthly. Two properties keep them safe.
- Reproducible: given the same orders, the same tree and the same rule versions, a run produces the same result. That requires fixing the cutoff time and time zone for each period, and storing the rule version used.
- Idempotent: if a job is interrupted and started again, it must not pay twice. Each commission carries a unique key (for example order, bonus and period), and the database refuses a second row with the same key.
A preview mode is also valuable. The business can run a period, review the totals and individual lines, and approve it before any balance is credited. Many errors in the plan are caught at this stage by people who know what the numbers should look like.
Refunds, returns and clawbacks
A sale is not final the moment it is paid for. Refunds and chargebacks can arrive days or weeks later. The engine needs a defined policy for what happens to commissions already earned on that order: reverse them, hold them until a refund window closes, or reverse them against future earnings. Whatever the plan says, the engine should apply it through new ledger rows linked to the original ones, not by quietly altering history.
Rank and qualification add another layer. If a refund drops a member below the volume needed for their rank, does the rank change in this period or the next? These are plan decisions that a developer should not guess. We ask for the answer in writing during scoping.
Test with worked examples before launch
The most useful test data is a set of worked examples written by the client: small trees, a few orders, and the payout each person should receive, calculated by hand or in a spreadsheet. The engine is then tested against those examples, line by line. Every rule gets at least one example, plus edge cases such as ties, caps, refunds and inactive members. When the plan changes later, the examples change with it and become a regression suite.
This is how we make a plan traceable to a document, which also helps with the legal review described on our compliance page. Direct selling is regulated, and the client is responsible for the plan and its disclosures. Our job is to implement the documented plan exactly and to show our work.
What to ask any vendor about their engine
- Which numeric type do you use for money, and where do you round?
- Is there an append-only ledger, and can you trace one payment back to an order and a rule version?
- What stops a job from paying twice if it restarts?
- Can I preview a period before money moves?
- How are refunds and rank changes handled?
- Do I own the code and the data?
Our own answers are described on the page for automated commission and payout engines. Typical timelines and price ranges are on the pricing page; a written quote follows a scoping conversation, and the client owns the code it pays for.
If you have a plan document and want to see how it would turn into rules and tests, chat with us on WhatsApp at +1 (929) 450-3261 and tell us the plan type and your markets.