Before you trust a number
A number on a screen is an output. Before it goes into a payout decision, a client conversation, or a dispute, four questions have cheap answers and one expensive one.
The four questions
Section titled “The four questions”1. Is the data fresh?
Section titled “1. Is the data fresh?”Look at the state of the last delivery, not at the page’s own timestamp. If the platform is showing “data update delayed”, stop treating the figures as today’s, whatever the screen says elsewhere. A delayed feed is a known, visible state — it is not a licence to read stale numbers as current.
2. Which layer produced it?
Section titled “2. Which layer produced it?”Every commission figure has a source label. Read it. If a total changed between two days and the label changed with it, the explanation is the source chain, not a data error. See Understanding your commission.
3. Is the record current?
Section titled “3. Is the record current?”Source records are versioned and append-only. Any count or total that reads the whole replica table is including historical versions. Compare current records with the source’s declared count.
A discrepancy that appears only for a subset — a handful of agents, one dataset — after a delivery is the signature of a version-filtering mistake. Textbooks and reality agree on this one.
4. Is the attribution confirmed?
Section titled “4. Is the attribution confirmed?”Check whether the commission belongs to the agent you think it does. A policy’s licence holder is not always the producer, and an unconfirmed relation is shown as pending rather than guessed. See Policies, clients, and license holders.
What a healthy delivery looks like
Section titled “What a healthy delivery looks like”| Check | Expected result |
|---|---|
| Per-dataset row count and content hash | Match the manifest |
| Duplicate record identifiers in a delivery | None |
| Per-group row and amount controls | Zero mismatches |
| Re-importing the same delivery | Zero new source rows, no amounts changed |
| Operator-confirmed policy mappings after a refresh | Unchanged |
| Headline commission for a sample of agents | Dashboard total equals the operations summary |
The last row is the cheapest read-back you have. Those two figures come from the same query, so a difference between them is a defect with no ambiguity about who is right.
Reconciliation hygiene
Section titled “Reconciliation hygiene”- Compare current records on the platform side with the source’s declared counts. The replica also keeps historical rows; that number is larger on purpose and will never match.
- Money is reconciled per currency and per status. A single blended total will hide a mismatch that a per-group comparison catches.
- Treat a failed controls check (
CONTROL_MISMATCH) as a hard stop. The import intentionally did not advance, the previous complete batch is still in place, and the fix is on the source side or in the delivery — not in the platform’s stored data. - Do not “help” by re-importing something that failed. Re-reading a delivery is safe and idempotent; forcing a batch past a failed check is not.
Red flags
Section titled “Red flags”- A figure that differs between two screens that read the same field.
- A total that changes with no new delivery.
- A number that is suspiciously round or suspiciously doubled after a delivery. Doubling is the classic symptom of a version-filtering miss, and it is not subtle once you look for it.
- A zero that cannot be explained by any of the legitimate reasons — no commission, unlicensed, frozen, deferred, relationship pending, data unknown. A real zero and an unknown are different states.
- A page that is missing rather than disabled. Missing usually means a permission; disabled means state the platform is telling you about.
What to capture when you escalate
Section titled “What to capture when you escalate”Bring these, and the investigation starts immediately:
- Which delivery, and when the source says it was checked.
- When the platform finished importing it.
- Per-dataset row counts and the controls result.
- Which agents or objects you compared, and the values on both sides.
- The reproduction: which screen, which account, which endpoint.
Do not paste client names, policy numbers, or account identifiers into a ticket that does not need them. A count and a group key are usually enough to identify a problem; the people in the data are not part of the diagnosis.