At a glance
The client
The same platform operator, building the revenue-share engine that sat underneath the transactional product. Revenue was split across a distribution chain — the organization, its agents, and their sub-agents — with the end user's rate determined by wherever they sat in that chain.
The challenge
Commission looks like a percentage field until you try to build it across a hierarchy. Then it becomes four separate problems, and getting any one of them wrong produces either a silent margin leak or an argument nobody can settle.
Defaults that cascade to accounts that don't exist yet
A rate set at organization level had to apply to every account currently beneath it and to every account created afterwards — so the default had to resolve rather than propagate.
A constraint that only permits movement one way
Any tier could raise its own rate but never set one below the level above it. Enforcing that meant validating a proposed change against the entire subtree beneath it, not just its immediate parent.
Disputes are about dates, not rates
When a party questions what they were paid, the argument is almost never about the current rate — it's about which rate applied on a particular day. That makes the change history the product.
Settled history has to stay settled
A rate change made today cannot retroactively alter transactions already settled under the previous rate. Settlement had to resolve against the rate in force at the time of the transaction.
What we did
-
Modeled the rate as an effective-dated record, not a field
Every rate is a row with an effective date and time rather than a value that gets overwritten. Changing a rate appends history instead of destroying it — so the audit trail is a consequence of the design.
-
Made the constraint a pre-commit validation across the subtree
Before any change commits, the system walks every level beneath the changing tier and rejects the write if the result would leave any descendant below the ceiling set above it. No interface path can bypass it.
-
Resolved rates at read time by walking the hierarchy
Rather than writing a rate onto every account, the applicable rate is resolved by walking up the tree to the nearest explicit override. New accounts inherit correctly with no backfill.
-
Separated organization defaults from tier overrides
An organization-wide default and a specific agent's override are different kinds of record, not the same field written by different users. Keeping them distinct is what makes it possible to answer why a given account has the rate it has.
-
Made settlement read the historical rate
Settlement resolves the rate in force at the transaction's timestamp, so past settlements stay correct permanently and a rate change never rewrites financial history.
The results
The engine resolves rates correctly across six tiers, with organization-level defaults reaching accounts created long after the default was set. The one-directional constraint is enforced at the data layer, so no tier can undercut the level above it through any interface path.
Every rate change carries its effective date and time, which means questions about what applied when have an answer rather than a negotiation. Settled transactions remain settled at the rate that was in force when they occurred.
