- Reconciliation starts with an explicit, documented definition of correct.
- Stable cross-reference IDs are absolutely essential.
- Deletion markers separate intentional removals from failed syncs.
Last time, we looked at recovery. And now we are covering reconciliation.
Too often, reconciliation becomes guesswork when an integration or connected system has no agreed-upon definition of what is "correct". Before building sync behavior, decide what each connected system owns, document that ownership, and document any likely exceptions.
Write down the data contract
A simple data contract captures which records and fields sync, which system is wins in a conflict, how conflicts are otherwise handled, and what happens when records are deleted or merged. It also describes any intentional differences, such as excluded records or fields that should never sync. Otherwise, during an audit, a valid data difference can looks just like a data issue.
Assign ownership field by field
Let's say your customer's CRM owns a contact name and phone number while your product owns the plan tier and usage. If both systems can update the same field, define what happens before a customer escalation: one side wins, values merge, or a person reviews the conflict and makes a call. Track (log) the overwrites and don't simply discard the prior value without noting it.
Make identity explicit
Names and email addresses are not good candidates for unique IDs because they can change or be shared. Instead, store a stable cross-reference for the source and destination IDs, scoped to the customer and connected system. That mapping helps the integration find the counterpart record during sync and and during reconciliation.
Make writes safe to repeat
Use an upsert keyed by a stable external ID instead of a create. Use an API's idempotency key when available, and deduplicate incoming events. If a request times out, check whether it succeeded before issuing another action. Taking these steps will help to reduce duplicate effects. However, they don't prove the value written was correct. You'll still need to validate the data mappings and business rules.
Plan for deletions and merges
Be particularly careful with deletions and merges. A deletion marker can distinguish an intentionally removed record from one that failed to sync (but should have). When records merge, update the ID mapping to point to the surviving record. And don't assume every missing record should be restored.
Make reconciliation predictable.
These decisions make reconciliation more predictable: your team knows which records correspond, what "correct" means, and which system wins.
The next post covers the operations (progress tracking, error handling, and ordering) that let the integration pick up where it left off after the drift.


