Why should the main business system and commission ledger avoid unrestricted two-way synchronization?
The main system should own business facts such as orders, payments, and staff assignment, while the commission ledger owns rules, calculations, and settlements. Send facts into the ledger in one direction and correct them with new events, reversals, and reconciliation. Consider limited return messages only after every field has one authoritative writer, idempotency, and an explicit conflict process.
The problem is not whether two systems can call each other's APIs. It is whether both can rewrite the same fact. If the main system changes an order to 90,000 while a manual commission adjustment writes 100,000 back, the next synchronization has no legitimate winner. Refunds, split orders, payments across periods, and staff transfers compound this ambiguity. Wavesteam assigns ownership before choosing an interface direction.
When agreeing deliverables, handover, and ownership boundaries, also compare How can commission data be restricted to authorized accounts? and Who owns the data and intellectual property in a custom software project?; the linked guidance adds context that should be considered in the same decision.
Long-term effect of three patterns
| Pattern | Write rule | Advantage | Long-term risk | Assessment |
|---|---|---|---|---|
| Shared database or direct table changes | Both applications can alter the same record | Quick initial implementation | Tight coupling, weak audit, upgrades affect each other | Not suitable for formal settlement |
| Full two-way API synchronization | Each side overwrites or merges by time | Appears consistent | Update loops, conflict loss, duplicate effects after retry | Only for a few clearly owned fields |
| Facts flow into the commission ledger | Main system writes facts; ledger writes calculation and settlement | Clear accountability, replay, and audit | Requires events, snapshots, and reconciliation | Preferred commission design |
Create a field-level responsibility table. Order number, transaction amount, refund, payment time, and customer ownership come from the main system. Rule version, commission basis, calculation detail, approval state, and payment batch belong to the ledger. The ledger may expose an “already settled” batch status for read-only display in the main system, but the main system cannot edit settlement entries. One-way ownership is about one writer per fact, not one physical network connection.
Synchronization messages carry a global event ID, business reference, fact version, occurrence time, and source. The ledger deduplicates by ID and handles out-of-order versions. Ten retries after a timeout still produce one business effect. A refund adds a new fact rather than deleting the order event, and the ledger creates a negative adjustment. AWS guidance on event sourcing explains immutable history and state reconstruction along with complexity and eventual consistency. A small system may not need a full event platform, but immutable ledgers and idempotency remain useful.
Each finalized settlement fixes the included fact versions, rule version, organizational relationship, manual changes, calculation detail, and approver. A later change enters the next adjustment batch rather than overwriting a paid record. Month-end reconciliation then compares main-system facts, commission accrual, and actual payments and classifies differences such as unsynchronized, excluded by rule, manual adjustment, or unpaid.
Heavy reporting may use separate write and read models, as described by the CQRS pattern, accepting brief read-model delay. The interface must show data cutoff or sync state rather than imply real time. An OpenAPI contract should fix field meaning, monetary units, time zones, nulls, errors, and version policy.
A return message is reasonable when the ledger alone creates it—for example, sending “batch settled” to the main system. It still needs one owner, an idempotency key, retry and dead-letter handling, a manual conflict path, and permission controls that do not expose sensitive amounts.
Acceptance simulates duplicates, reordering, outages, cross-period refunds, staff transfers, rule changes, and manual reversals. Wavesteam requires a reconciliation report and failure exercise rather than treating an HTTP 200 response as proof of correct accounting.