Xero integration guide

Overview

The OneHQ Xero integration is read-only. It pulls financial data from your clients' Xero organisations to power compliance workflows, but never writes, modifies, or deletes any data in Xero.

Once connected, Xero data is used across several areas of OneHQ:

• BAS readiness — GST analysis, bank reconciliation checks, payroll data, risk engine anomaly detection
• Tax return preparation — P&L, Balance Sheet, Trial Balance comparatives, super compliance, BAS-to-return reconciliation
• Tax planning worksheets — live financial data for group-level year-end planning
• Financial snapshots — monthly income/expense trends on entity detail views
• Entity Financials tab — on-demand Xero report viewer (P&L, Balance Sheet, Trial Balance, BAS)

Data flow diagram

The diagram below shows how data moves between Xero and OneHQ. All data flows are one-way, from Xero into OneHQ.

Getting started

Before connecting Xero, make sure you have:

• An active OneHQ practice (Admin role required for initial setup)
• A Xero login with access to the client organisations you want to connect
• Entities created in OneHQ for the clients you want to link (with ABNs entered for automatic matching)

The connection process takes about 30 seconds and you can connect multiple Xero organisations at once.

Connecting to Xero

Connecting from an entity

You can also initiate a Xero connection directly from an entity's detail view. In the entity's Quick View panel, look for the Connections card — click "Connect Xero" to start the OAuth flow specifically for that entity. The newly connected organisation will be linked to that entity automatically.

Multiple staff connections

Multiple staff members can each connect their own Xero accounts. OneHQ aggregates all connected organisations across all staff in the practice. This is useful when different team members manage different Xero clients.

Practice subscription (optional)

If your practice itself uses Xero for invoicing, you can connect a separate "Practice Subscription" under Settings > Connections. This links your firm's own Xero organisation for internal billing features, and is separate from client connections.

Entity mapping

Each entity in OneHQ can be linked to one Xero organisation. This mapping determines which Xero data appears on that entity's jobs, financial views, and compliance checks.

How entities get mapped

There are three ways an entity gets linked to a Xero organisation:

1. Automatic ABN matching — during the OAuth connection, OneHQ reads each Xero org's ABN and matches it to unmapped entities with the same ABN. This is the most common method.
2. Manual mapping in Settings — expand the Xero section in Settings > Connections. Each connected org has a dropdown showing all entities — select the matching one.
3. Manual mapping on the entity — in the entity's Quick View panel under Connections, use the "Link Xero org..." dropdown to select from available (unlinked) Xero organisations.

Re-running automatic matching

If you add ABNs to entities after connecting Xero, you can re-run automatic matching. In Settings > Connections, expand the Xero section and click the "Auto-match" button. This will check all connected orgs against unmapped entities.

Unlinking an entity

To unlink an entity from its Xero organisation without disconnecting from Xero entirely, either:

• In Settings > Connections, change the entity dropdown to "Not linked"
• On the entity's Quick View, click the "x" button next to the linked Xero org name

This removes the mapping but keeps your Xero OAuth connection active for other entities.

What data syncs

All Xero data is fetched on-demand — when you open a job detail, financial view, or compliance check. There is no background sync or scheduled polling. This means data is always current when you view it.

Reports

Transactions

Payroll

Reference data

How data appears in OneHQ

Once an entity is linked to a Xero organisation, financial data appears automatically across several views:

BAS job detail

When you open an Activity Statement (BAS) job, OneHQ fetches BAS readiness data from Xero. You'll see:

• GST amounts — current period GST collected and paid, compared against estimates
• Bank reconciliation status — whether the Xero bank account is reconciled for the BAS period
• Risk engine analysis — 12 automated anomaly checks on transactions, with traffic-light severity ratings
• Payroll reconciliation — W1/W2 amounts, wages payable movements, per-employee pay run details

BAS job detail — Current BAS Summary with GST amounts from Xero, Bank Reconciliation status, Wages Reconciliation with W1/W2 figures, and Risk Engine traffic lights.

Tax planning worksheet

The Tax Planning job detail pulls live Xero data for each entity in a client group, populating an interactive planning worksheet with current year financials, payroll data, unreconciled transactions, and projected tax estimates.

Entity detail — Financial Snapshot

When viewing an entity, a Financial Snapshot card shows a monthly bar chart comparing current and prior financial year income and expenses. This auto-loads from Xero when you view the entity.

Entity Financials tab

The Financials tab on any entity provides an on-demand report viewer. Select a report type (Profit & Loss, Balance Sheet, Trial Balance, or BAS), choose a date range, and click "Fetch Report" to pull the data directly from Xero.

Entity detail — the Xero badge appears next to the entity name, and the Profit & Loss card (top right) shows monthly income, expenses, and net profit pulled live from Xero.

Tax return job detail

For Tax Return jobs, OneHQ checks tax readiness by pulling:

• P&L and Balance Sheet — current and prior year comparatives
• Trial Balance — full account listing for review
• Super compliance — pay run super contributions vs SG requirements
• BAS-to-return reconciliation — checks BAS amounts tie back to the annual return
• Division 7A analysis — loan account detection for companies

Tax Return job detail — Tax Return Overview with P&L figures from Xero, traffic light signals for Tax Review, BAS Reconciliation, Payroll & Super, Division 7A, and Prior Year comparisons. The "Open in Xero" button links directly to the Xero organisation.

When Xero is not connected

If Xero is not connected, or an entity is not linked to a Xero organisation:

• BAS job details show "Connect Xero" prompts instead of financial data
• Tax Return readiness checks show "No Xero connection" status
• The Financial Snapshot card is hidden entirely
• The Entity Financials tab shows an empty state with a "Connect Xero" link

BAS job detail without Xero — shows "No Xero Org" state with prompts to connect, instead of live financial data.

All other OneHQ functionality works without Xero — it simply enhances compliance workflows with live financial data.

Configuration & settings

Connection management

Entity settings — the Connections card shows whether the entity is linked to a Xero organisation, with options to connect or change the mapping.

All Xero connection settings are in Settings > Connections. From the expanded Xero section you can:

• View all connected Xero organisations and their mapped entities
• Change entity mappings via the dropdown on each row
• Connect additional Xero organisations ("Connect More Orgs" button)
• Refresh the list of available organisations ("Refresh" button)
• Disconnect individual organisations or all at once
• Re-run automatic ABN matching ("Auto-match" button)

Display preferences

Under Settings > Display & Preferences, you can toggle:

• Show Xero Links — controls whether "Open in Xero" quick-link buttons appear on job pages
• Show XPM Links — controls Xero Practice Manager deep-link buttons

Xero deep-links

If you set a Xero slug on an entity (in the entity's settings), OneHQ will show "Open in Xero" buttons on job detail pages. These open the relevant Xero page for that organisation directly in your browser. The slug is a short code found in your Xero URLs.

Risk engine configuration

The risk engine settings (under Settings > Practice Details) affect how BAS readiness data from Xero is analysed. You can choose from three presets:

• Fast — fewer checks, lower sensitivity (good for bulk review)
• Standard — balanced analysis (recommended for most practices)
• Conservative — thorough checks with lower materiality thresholds

These presets control materiality floors, scaling factors, and which anomaly rules are active.

Disconnecting Xero

You can disconnect Xero organisations individually or all at once.

Disconnect a single organisation

1. Go to Settings > Connections
2. Expand the Xero section
3. Click the "Disconnect" button on the specific organisation row
4. Confirm the disconnection

This revokes OAuth access for that single organisation, unlinks any entities mapped to it, and removes it from your available connections. Other Xero organisations remain connected.

Disconnect all organisations

1. Go to Settings > Connections
2. Click the "Disconnect" button on the main Xero row
3. Confirm the disconnection

This revokes all OAuth access, unlinks all entities from their Xero organisations, clears any practice subscription connection, and removes all stored tokens.

Revoking access from Xero's side

You can also revoke OneHQ's access directly from Xero. Go to Xero Settings > Connected Apps and disconnect OneHQ from there. Note that this won't automatically update the connection status in OneHQ — you should also disconnect from within OneHQ Settings to keep things clean.

Frequently asked questions

Troubleshooting