Why your commission number has one source of truth
An agency can load its own income results, a processor can approve results, and legacy settlements can exist all at once. Here is why we show one number and label where it came from.
Ask three systems how much an agent earned and you will often get three answers. The agency loaded its own income results. The carrier’s processor approved some of them. The legacy ledger has settlements going back further than either. None of the three is wrong; they are describing the same money from different vantage points, at different moments.
The tempting fix is to blend them. Take the processor’s number where it exists, fall back to the ledger, top it up with the agency’s own loading. It produces a single figure on the screen and it is the wrong engineering decision, for one reason: a blended number cannot be audited. When an agent asks why their commission changed, the only honest answer is “because we changed which system we were reading” — which is not an answer.
One number, chosen by priority
Heysen resolves commission through a priority chain. The first layer that has anything to say wins:
- Static monthly income results — the agency’s own loaded results.
- Approved results from the carrier or processor — cash-basis results for the current year.
- Legacy settlements — net amounts from the settlement records.
If none of the three has data, the agent has no commission figure yet, and we say so.
Two consequences matter more than the ordering itself:
Layers are never added together. An agent who appears in both the agency’s loading and the processor’s approved results sees one of those totals, not their sum. Summing them is the single easiest way to double an agent’s income, and it is a mistake that looks entirely plausible on a dashboard.
The answer carries its own label. The API returns which layer produced the number, and the app shows it. “Your commission changed and here is which source changed” is a conversation; “your commission changed and we are not sure why” is a support ticket.
Consistency is a feature, not a coincidence
Two screens show a commission total: the agent’s dashboard and the operations summary. They are produced by the same query, deliberately. Ask any two systems for the same number and they will eventually drift. Ask one system twice and you get one number.
That is why a disagreement between those two screens is treated as a defect rather than a rounding difference. There is no legitimate reason for them to differ, so there is nothing to interpret.
Zero is a claim
The chain also decides what to do when there is nothing to show. Refusing to print a number is uncomfortable — an empty cell looks like a bug — so the pull toward displaying 0 is strong. We resist it, because 0 is a claim: it says an agent earned nothing. The truth is often different. The agent is not licensed yet. The result is frozen. The payment is deferred. The policy’s owner of record is still being confirmed. The source simply did not supply the field.
Those are six different situations, and only the first of them means “no commission”. Collapsing them into a zero converts “we do not know” into “there is nothing” — and those two lead to opposite decisions when a payout is being processed. So the platform carries the distinction all the way to the screen, and refuses to guess at the edges of what it knows.
It is a less satisfying demo. It is a considerably better ledger.