Xero integration reconciliation
Save the integration intent before sending it to Xero
A durable operation record gives retries and support a shared source of truth. Record the target organisation and expected request before making the external call.
In this article
Create the local operation
Validate the business request and resolve the trusted Xero connection. Save the internal document identity, target organisation and operation type in a durable record.
Keep the intended request stable for an idempotent retry. A background worker should not rebuild a different payload from mutable current data while reusing the same request key.
Record a payload fingerprint or version under the application's data policy so a changed intent can be detected without exposing unnecessary financial details in logs.
{
"operationId": "invoice-export-example-38",
"internalDocumentId": "invoice-example-91",
"xeroTenantReference": "connection-tenant-example",
"requestVersion": 1,
"state": "ready",
"xeroResourceId": null
}Send with explicit context
Pass the tenant-specific token and organisation information through the supported client path. Avoid shared mutable settings that one concurrent job can replace while another request is being prepared.
Use the applicable idempotency support and preserve its key for the same request under the documented window and semantics.
Record transport and provider outcomes separately. A validation rejection, rate limit and lost response need different next actions.
Persist the confirmed mapping
When the response establishes creation, save the returned resource identifier with the local operation. The application should use that mapping for later reads and updates.
Handle a local failure after the external success as an uncertain state. The external effect cannot be rolled back by the local transaction failing.
Use a recovery process that can inspect the provider state and complete the mapping without creating another document blindly.
Test restart at each boundary
Stop the worker before send, after send and after the response but before local persistence. Resume it and verify that each case reaches a coherent outcome.
Include a changed payload under an existing operation identity and reject that conflict explicitly. A new business intent needs its own deliberate operation, not an accidental reuse of a retry record.
The implementation is ready when support can explain what was intended, where it was sent and what evidence establishes the result after a process restart.
Primary sources
Xero: managing tokens and identifiersXero: idempotent requestsReferences checked 11 September 2026.