Xero integration reconciliation
Track unresolved Xero outcomes separately from retry counts
A busy retry loop can look active while business documents remain uncertain. Measure confirmed mappings, unresolved age and reconciliation results.
In this article
Define the operation population
Count the business export or update operation once, even if it has several transport attempts. Keep attempt metrics for diagnosis without allowing them to inflate completion figures.
Separate ready, in-flight, confirmed, rejected and outcome-unknown states. Use names that describe what the system knows rather than one broad failed bucket.
Record eligibility rules for cancelled or superseded local work.
Measure confirmed completion
A completed operation should have the required provider result and local mapping, not merely a successful HTTP exchange. Where the API returns item-level results, evaluate the relevant items under the endpoint's contract.
Track time from accepted local intent to confirmed outcome. Include waiting caused by rate limits, revoked connections and manual review.
For an illustrative batch of 100 exports, 95 confirmed, three rejected and two uncertain should remain those three categories. Reporting 98 processed hides the two records whose external outcome still needs investigation.
Monitor reconciliation quality
Track the age of uncertain operations and the proportion resolved without duplicate creation. Record mismatches by meaningful category, such as missing mapping, unexpected status or ambiguous candidate.
Use controlled duplicate checks suited to the integration's identity model. Similar totals alone cannot establish that two documents are duplicates.
Keep unresolved items assigned to an owner with a clear next action.
Verify business agreement
Compare representative local and Xero records using the fields the integration is responsible for. Account for legitimate changes made in Xero under the agreed ownership policy.
Do not treat every difference as a sync failure or overwrite it automatically. Some differences require a business decision.
Accept the integration when confirmed work is traceable, uncertainty remains visible and recovery preserves document identity. A low API error rate is useful operational evidence, but it does not by itself prove that the two systems agree.
Primary sources
Xero: official Accounting API specificationReferences checked 11 September 2026.