A Xero timeout needs reconciliation before another invoice

A timeout does not mean nothing happened

An application sends a synthetic invoice creation request to Xero. Xero accepts it, but the connection closes before the response reaches the application. If the application immediately creates another invoice with a new operation identity, it can duplicate the business document.

Treat that state as outcome unknown. Preserve the request identity, target organisation and intended payload so the integration can investigate or safely retry under the API's supported rules.

A generic failed status loses the distinction between a rejected request and an accepted request whose response was lost.

Use provider protection and a local ledger

Xero's documented idempotency mechanism caches mutating-request responses for six minutes from the first call. That limited window helps with transient retries, but it is not a permanent record of your business operation.

Keep a local integration ledger that outlives the transport retry window. Record the internal operation, Xero tenant, request identity and resulting Xero resource identifier when known.

Keep organisation identity explicit

A Xero resource identifier must be interpreted with the connection and organisation context your application maintains. Background work should carry trusted tenant-specific context rather than relying on a mutable global client setting.

Verify that the user or business process is authorised for the selected organisation before queueing work. The worker should use the connection associated with that scope and handle revoked access visibly.

Cross-organisation mistakes can be more serious than an ordinary duplicate, so include them in the integration's acceptance tests.

Decide which system owns each field

An integration can create a draft from operational data while Xero later contains accounting changes. Define which fields your application may update after creation and which state it only reads.

Do not overwrite a Xero-side change merely because the local copy differs. A difference may be a legitimate business action requiring reconciliation rather than a failed sync.

Keep accounting treatment and approval decisions with the responsible business owner. The integration should implement the agreed mapping, not infer it from a matching total.