How invoice sync to Xero works

Summary

Once your Xero connection is active, Torqueflow can push sales invoices and purchase invoices into Xero automatically, and pull payment events back so that an invoice paid in Xero is marked paid in Torqueflow. This guide explains what gets synced, the per-invoice sync badges, how to handle sync errors, and how payment events flow back from Xero.

Prerequisites

• An active Xero connection. See “Connecting Torqueflow to Xero”.
• Each nominal code used on an invoice line has a Xero account code populated. Edit nominal codes from Settings → Finance → Nominal Codes.
• For sales invoices, the customer record should have a valid email if you want it populated in Xero (a missing email is fine — it is omitted, not posted as blank).
• Currency: this version syncs GBP only. Invoices in other currencies will fail with a currency_mismatch error.

Permissions

• settings.integrations.manage to change auto-sync toggles. Held by the Owner role by default.
• finance.xero.sync to use the per-invoice Sync now button.

Steps

Turn auto-sync on or off

1. Go to Settings → Integrations → Xero.
2. In the Auto-sync panel, set the three toggles:
   • Automatically sync new invoices to Xero — master switch. On by default.
   • Sync sales invoices — On by default.
   • Sync purchase invoices — On by default.
3. Changes save immediately.

If auto-sync is off, invoices will not push automatically, but the Sync now button on each invoice still works as a manual override.

Read the Xero sync badge

Every sales invoice and purchase invoice shows a Xero sync badge in the list view and on the detail page.

• Green pill - “Synced to Xero” — the invoice is in Xero and matches what is in Torqueflow. Hover for the timestamp it was last synced.
• Grey pill - “Pending” — the push is queued but not yet sent. Usually this clears within a minute.
• Red pill - “Sync failed” — the last push hit an error. Hover the badge for the reason. A Sync now button is available to retry once you have fixed the underlying issue.
• No badge — your organisation has no active Xero connection.

Push an invoice manually

1. Open the invoice (sales or purchase).
2. Click Sync now.
3. A toast confirms “Queued”. The badge updates within a minute.
4. If the push fails, the badge turns red and the tooltip shows the reason.

Sync now works even when auto-sync is off. It also works on invoices that have permanently failed automatic retries.

Expected Outcome

After the first auto-sync round (or after a successful manual Sync now), your sales invoices appear in Xero under Sales → Invoices, your purchase invoices appear under Business → Bills, and any new customers or suppliers appear in Xero’s Contacts. Updates to existing invoices in Torqueflow re-push and reflect in Xero within about a minute.

Payment events from Xero

Payments recorded in Xero flow back into Torqueflow automatically.

Marking an invoice paid in Xero flips the Torqueflow invoice to Paid within about 5 minutes. A payment row appears against the invoice with the payment method “Xero Sync” — this is a system payment method that is auto-created for each organisation, and you should not delete it.

Partial payments in Xero (for example £50 followed by £30 against a £100 invoice) arrive independently. The Torqueflow invoice ends up Part paid with the correct paid amount.

Deleting a payment in Xero soft-deletes the corresponding Torqueflow payment row (the audit trail is preserved). The invoice reverts to Part paid or Unpaid as appropriate.

Voiding an invoice in Xero flips the Torqueflow invoice to Void. The work-order link is freed unless the work order has already been re-invoiced locally — in that case the void still applies to the Xero side, the existing live invoice is untouched, and the conflict is captured in the audit log.

Invoices created directly in Xero (not through Torqueflow) are not pulled into Torqueflow in this version. Only invoices that originated in Torqueflow stay in sync.

Self-healing nightly check

A reconciler runs every night at 02:00. It re-checks any invoice or payment modified in Xero in the last 7 days against Torqueflow and applies any updates that were missed (for instance, a webhook that did not arrive). User-visible effect: an occasional invoice that looked stuck the night before is fixed by morning.

Troubleshooting

The error reason is shown in the red badge tooltip. The most common reasons:

Problem: Badge says “Unmapped nominal code”. Cause: One of the invoice lines uses a nominal code with no Xero account code set. Fix: Settings → Finance → Nominal Codes. Edit the offending nominal code, fill in the Xero account code, save. Return to the invoice and click Sync now.

Problem: Badge says “Currency mismatch”. Cause: The invoice currency differs from your organisation default. This version of Torqueflow syncs GBP only. Fix: Re-issue the invoice in GBP. Multi-currency support is planned.

Problem: Badge says “Connection not active”. Cause: Your Xero connection is in pending_credits, requires_reauth, grace_period, or disconnected. Fix: Settings → Integrations → Xero. Resolve the underlying state — top up credits, reconnect, or reconnect from scratch. Once the connection is active, click Sync now on the invoice.

Problem: Badge says “Contact collision - manual mapping required”. Cause: Two Torqueflow customers (or suppliers) share a name and Xero refused to create the second contact because Xero deduplicates contacts by name. Fix: Rename one of the local entities in Torqueflow (for example, add the postcode or the company name) so the names differ, then click Sync now. If you cannot rename them, contact support — manual remapping is a support task in this version.

Problem: Badge says “Work order already re-invoiced”. Cause: An invoice was voided in Xero, but Torqueflow had already re-invoiced the same work order locally. Fix: No automatic action. The void still applied in Xero. Review the work-order audit log to confirm which invoice is live. Contact support if anything looks wrong.

Problem: Badge says “Payment delete - no match”. Cause: Xero deleted a payment that has no matching Torqueflow payment row. Usually the payment originated outside Torqueflow. Fix: Check the Xero payment audit and the Torqueflow invoice audit. Usually safe to ignore. Contact support if it persists.

Problem: Badge stays grey for several minutes. Cause: Xero is rate-limiting or returning transient errors. The system retries automatically. Fix: Wait. The badge will turn green when the push succeeds. If it goes red, follow the specific reason.

Problem: “App revoked”. Cause: Either the Xero subscription has lapsed, or the app was de-authorised in Xero → Connected Apps. Fix: Re-enable on the Xero side, then return to Settings → Integrations → Xero and reconnect.

Notes

• Currently no per-customer or per-supplier opt-out. The two toggles (sync sales / sync purchases) apply to the whole organisation.
• Credit notes are not synced in this version.
• Historical invoices created before you connect to Xero do not auto-backfill. Use Sync now on individual invoices if you want them in Xero.
• Payments recorded in Torqueflow are not pushed to Xero. The flow is one-way for payments: Xero → Torqueflow only.
• Invoices that have permanently failed (three retry attempts) stop being retried automatically. The Sync now button is always available.