Xero integration reconciliation
Reconcile existing Xero mappings before enabling the new sync
A replacement integration needs to recognise documents created by the old one. Start with identity and ownership so the first run does not recreate history.
In this article
Inventory the existing relationship
Collect local document identities, known Xero resource identifiers and organisation mappings from the current integration. Assess missing or ambiguous links.
Do not assume a new connector can infer all history from document numbers or totals. Determine which identifiers are stable and unique under the actual business process.
Keep the old integration's write authority controlled while the new mapping is prepared.
Import and validate mappings
Load known relationships into the new ledger with provenance. Read representative provider resources and verify that they belong to the intended organisation and local document.
Keep uncertain links in a review state. A guessed mapping can cause the new integration to update the wrong financial document.
Record which fields the replacement may own and which it must preserve from Xero-side changes.
Run a comparison phase
Use read-only comparison where practical before enabling mutations. Report differences by cause rather than automatically repairing every mismatch.
Exercise recent, older and manually changed documents. The integration needs to handle the real history, not only clean records created by its own test code.
Use safe synthetic operations to validate new-write and unknown-outcome recovery independently of historical mapping.
Transfer write ownership once
Stop or fence the old writer before enabling the replacement for the same scope. Include scheduled jobs and queued retries that could resume later.
Roll out a controlled set of documents or organisations and verify confirmed mappings and reconciliation results. Keep rollback aligned with any new state the replacement has written.
Retain the old mapping evidence and operation history according to the reporting and recovery requirements. The migration is complete when the new system can distinguish existing documents from new intent and maintain that relationship without duplicate creation.
Primary sources
Xero: managing tokens and identifiersReferences checked 11 September 2026.