Xero Integration
Link POS sales data to Xero: OAuth connect, configure sync schedule and accounts, run manual sync, and review history.
Open the screen: Sidebar → Third Party Integration → Xero Integration
Access requirements
You need the Xero integration add-on, Xero enabled in tenant settings, and XERO INTEGRATION module permission.
In-app sub-pages (via hub cards or XeroNav): Overview (/xero-accounting), Sync Settings, Sync History. The callback route (/xero-accounting/callback) is used automatically after OAuth — you do not open it manually.
Connect and hub (Overview)
What it does
Two-step stepper until connect + sync settings are complete; then shows connection status and shortcuts.
Step-by-step — first-time setup
- Open Xero Integration.
- Step 1 — Connect to Xero: read the four connection steps, then tap Connect to Xero (Connecting...).
- Sign in on Xero, pick organisation, grant permissions — browser returns via callback.
- On callback success: Success / Xero account connected successfully — redirected to the hub.
- Step 2 — Configure Sync: fill Configure Sync (same fields as Sync Settings below), tap Save & Finish Setup.
When fully configured
- Connected badge with organisation name, Last sync, Token expires.
- Cards: Sync Settings, Sync History.
- Disconnect opens Disconnect Xero? — This will stop automatic syncing. Logs are kept and you can reconnect later.
Not connected
Not Connected card with Reconnect to Xero. Sync Settings and Sync History cards remain available for navigation.
Connection errors
- Failed to get authorization URL
- Xero Integration Not Enabled — tenant setting off; contact administrator.
Sync Settings
Open: Hub → Sync Settings, or /xero-accounting/sync-settings
What it does
Schedule automatic sync, pick sync type, map Xero accounts, and trigger manual sync.
Step-by-step
- Tap Edit Sync Settings to change values (view mode is read-only until edit).
- Configure fields below.
- Tap Save Settings (Saving...) or Cancel (reloads unsaved values).
- On success: Success / Sync settings saved successfully.
Fields
| Field | Required? | What to enter |
|---|---|---|
| Auto Sync Enabled | No | Switch — automatic sync on schedule |
| Daily Sync Time | Yes | Time input — sync runs daily at this time (default 01:00) |
| Sync Type | No | Sync All Transactions or Sync Daily Settlements |
| Bank Account | Yes | Xero BANK account — marks invoices paid |
| Sales Account | Yes | Xero REVENUE / SALES account for invoice income |
Validation
- Accounts required / Please select both bank and sales account.
- Daily sync time required
Manual Sync
| Sync type selected | Button | Result toast |
|---|---|---|
| Sync All Transactions | Sync Now | Sync Started — push invoices immediately |
| Sync Daily Settlements | Sync Now | Settlement Sync Started |
Sync History
Open: Hub → Sync History, or /xero-accounting/sync-history
What it does
Paginated log of sync records with expandable invoice details.
Step-by-step
- Open Sync History & Logs.
- Read Sync Records count.
- Tap Refresh to reload.
- Expand a row's Invoice Details (chevron) for Single Invoice or Split Invoice breakdown.
- Use pagination at the bottom (default page size 20).
Table columns
| Column | Meaning |
|---|---|
| Type | Entity type badge |
| Reference | Sync reference |
| Order ID | Linked entity id |
| Invoice Details | Single or split invoice — expand for IDs and amounts |
| Synced At | Localised timestamp |
Empty: No sync records found — Sync records will appear here once you start syncing data with Xero.
OAuth callback
After Xero authorization, the app opens callback automatically. Missing code or state shows Connection Error and returns to the hub. Success clears status cache and redirects to Xero Accounting within a few seconds.
Permissions
| What you need | Why |
|---|---|
| XERO INTEGRATION — READ | Open pages and view status |
| CREATE | Connect to Xero / Reconnect |
| UPDATE | Disconnect, edit sync settings, Sync Now |