Xero integration guide | OneHQ support

Q: What Xero permissions does OneHQ request?

OneHQ requests these read scopes: accounting.contacts.read — contact information accounting.payments.read — payments accounting.journals.read — journal entries accounting.reports.read, with the individual report scopes (profit and loss, balance sheet, trial balance, bank summary, tax, aged and executive summary reports) — P&L, Balance Sheet, Trial Balance, Bank Summary, published BAS/GST accounting.attachments.read and accounting.budgets.read — attachments and budgets payroll.payruns.read and payroll.payslip.read — pay runs and pay slips payroll.employees.read — employees payroll.settings.read — payroll configuration And these write scopes, for the actions described above (each also lets OneHQ read what it covers): accounting.settings — read the chart of accounts, tax rates and organisation info, set up the accounts a journal posts to, and archive or restore an account you reclassify accounting.manualjournals — create, update, post, reverse and void the journals Review prepares accounting.banktransactions — read bank transactions, and recode one where you ask OneHQ to accounting.invoices — read invoices, and approve a draft invoice and ask Xero to send it (only ever in your firm’s own Xero organisation, never a client’s) Every write is initiated by a user in your practice. OneHQ does not alter a ledger on its own.

Q: How do I disconnect from Xero?

Go to Settings > Xero Connections and click “Disconnect” on the organisation’s row. Organisations are disconnected one at a time. Disconnecting revokes OAuth access and unlinks entities from that Xero org. See the Disconnecting Xero section above for full details.

Q: Why can’t I see financial data for an entity?

Financial data only appears when an entity is linked to a Xero organisation. Check that: Your practice has a Xero connection (Settings > Xero Connections) The entity is mapped to a specific Xero organisation (check the client’s record under Connections, or Settings > Xero Connections) OneHQ can still read the organisation (in Settings > Xero Connections, an organisation under “Needs attention” has a “Reconnect” button)

Q: Can I reconcile bank accounts from OneHQ?

No. OneHQ reads reconciliation status from Xero (whether accounts are reconciled for a period), but actual reconciliation must be done in Xero. OneHQ’s BAS readiness check will flag if bank accounts are unreconciled for the BAS period so you can address it in Xero before lodging.

Q: What are the Xero API scopes and limitations?

OneHQ does not support the following Xero features (they are outside the integration scope): Creating invoices from scratch (OneHQ can approve and send a draft you already have, in your firm’s own Xero organisation only) Modifying or creating contacts Bank feed management or reconciliation Creating or modifying pay runs Managing Xero settings generally (OneHQ reads the chart of accounts, sets up only the accounts a journal needs, and archives or restores an account only when you reclassify it) Fixed asset management File/attachment uploads to Xero The integration is purpose-built for Australian accounting compliance workflows — BAS, tax returns, and tax planning. These are the workflows where Xero data adds the most value.

Overview

The OneHQ Xero integration is read-first. It pulls financial data from your clients’ Xero organisations to power compliance work, and it can write back to Xero only where you ask it to — posting the journals prepared in Review, recoding a transaction, recording a bank transaction from a OneHQ tool, adding or archiving an account a journal needs, and approving a draft invoice you choose to send from your firm’s own Xero organisation. It never records time and never creates an invoice.

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
Year-end review — Review (the journals you reclassify and post), Bank Rec, BAS & ATO reconciliation and the workpaper pack, all reading the ledger live

You stay in control of writes. OneHQ never alters a ledger on its own. Journals are prepared for you to review, and are only created, posted, reversed or voided when someone in your practice acts. It does not touch bank feeds or pay runs.

Data flow diagram

The diagram below shows how data moves between Xero and OneHQ. Most of it flows one way — from Xero into OneHQ, which reads Xero to do the work. OneHQ writes back only where you ask it to (see below).

Data flow: Xero → OneHQ

Xero
Your clients’ orgs

———→

Reads
(on-demand)

OneHQ
Your practice

Data from Xero	Used in OneHQ for	Direction
Profit & Loss	Tax Returns, Tax Planning, Year-end review	Xero → OneHQ
Balance Sheet	Tax Returns, Tax Planning, BAS readiness	Xero → OneHQ
Trial Balance	Tax Returns, Year-end review	Xero → OneHQ
Bank Transactions	BAS risk analysis (12 anomaly rules), BAS-to-return reconciliation	Xero → OneHQ
Bank Summary	Bank reconciliation status check	Xero → OneHQ
Manual Journals	BAS risk analysis	Xero → OneHQ
Payroll (Pay Runs)	BAS wages reconciliation, STP, Payroll Tax, Tax Planning, super compliance	Xero → OneHQ
Tax Rates	GST type classification for risk engine	Xero → OneHQ
Chart of Accounts	Account classification, risk analysis	Xero → OneHQ
Organisation info	ABN matching during connection setup	Xero → OneHQ

OneHQ writes to Xero only where you ask it to. The reads above power the work; the only writes are the journals prepared in Review (and posting them), recoding a transaction, recording a bank transaction from a OneHQ tool, or adding or archiving the accounts a journal needs when you ask it to, and authorising or emailing a draft invoice you choose to send from your firm’s own Xero organisation. OneHQ never touches bank feeds or pay runs.

Getting started

Before connecting Xero, make sure you have:

An active OneHQ practice (the System settings permission is needed to open Settings > Xero Connections)
A Xero login with access to the client organisations you want to connect
Entities in OneHQ for the clients you want to link (with ABNs recorded for automatic matching)

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

Connecting to Xero

1

Open Settings > Xero Connections

Navigate to Settings (gear icon in the sidebar), then click the Xero Connections tab. The Client organisations card lists every Xero organisation OneHQ can read.

2

Click “Connect to Xero”

Click the Connect to Xero button on the card. You’ll be redirected to Xero’s authorisation page. Sign in to Xero and select which organisations you want to grant access to.

3

Authorise access

Xero will show the permissions OneHQ is requesting. Click “Allow Access” to authorise. You’ll be redirected back to OneHQ.

4

Automatic ABN matching

Once connected, OneHQ reads each newly connected organisation’s ABN from Xero and matches it to the unlinked entity in your practice with the same ABN. Matched entities are linked immediately — no manual work needed. If more than one entity carries that ABN, OneHQ leaves the choice to you.

5

Review mappings

The list in Settings > Xero Connections shows every connected organisation and which entity each is mapped to, with the ones still needing a decision at the top. You can change a mapping at any time using the client picker on its row.

Tip: You can also connect Xero during the initial setup wizard. If you skip it, you can always connect later from Settings.

Connecting from an entity

You can also link a Xero organisation directly from an entity’s detail view. On the client’s record, look for the Connections card — click “Connect” on the Xero row to pick from the organisations already connected to your practice, each marked with whether its ABN matches. If the organisation isn’t connected yet, you go to Xero to authorise it, and OneHQ links it to that entity when you return (or asks you to pick if it can’t tell which one it is).

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 it separately under Settings > Integrations > Practice Xero. This links your firm’s own Xero organisation, so the invoices your firm has raised there show on each client’s record, and a draft invoice already sitting in it can be approved and sent when you send that client a document to sign. OneHQ never creates the invoice and never records time. This connection 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:

Automatic ABN matching — during the OAuth connection, OneHQ reads each newly connected Xero org’s ABN and links it to the one unmapped entity with the same ABN. This is the most common method.
Manual mapping in Settings — in Settings > Xero Connections, each connected org has a client picker on its row — select the matching entity.
Manual mapping on the entity — on the client’s record under Connections, click “Connect” on the Xero row and pick from the practice’s connected Xero organisations.

Best practice: Make sure your clients’ ABNs are recorded (OneHQ takes them from XPM) before connecting Xero. This ensures automatic matching works for as many organisations as possible, saving you manual mapping work.

Organisations that weren’t matched

Automatic matching runs when an organisation is first connected. If you add ABNs to entities afterwards, link the remaining organisations yourself: in Settings > Xero Connections, choose the “Not linked” filter above the list and pick the client on each row.

Moving an organisation to a different entity

To point an organisation at a different entity, pick that entity in the organisation’s row in Settings > Xero Connections. OneHQ asks you to confirm first, because the organisation’s working data — its modules, queries, journal register and portal links — moves with it. To stop OneHQ reading an organisation altogether, disconnect it (see below).

What data syncs

You always see current figures. OneHQ pulls the latest from Xero whenever you open a job, a financial view or a compliance check — nothing to refresh, no overnight copy to go stale.

Reports

Xero report	Used in
Profit & Loss	Tax Returns, Tax Planning, Year-end review
Balance Sheet	Tax Returns, Tax Planning, BAS readiness (wages payable), STP
Trial Balance	Tax Returns, Year-end review
Bank Summary	BAS readiness, Tax Planning (reconciliation gap)
Published BAS/GST	BAS & ATO reconciliation

Transactions

Xero data	Used in
Bank transactions	BAS risk analysis (12 anomaly rules), BAS-to-return reconciliation, contractor payments, TPAR
Manual journals	BAS risk analysis
General journals	Wages payable reconciliation
Payments	Unreconciled payment detection

Payroll

Xero payroll data	Used in
Employees	Employee name resolution across payroll views
Pay runs & pay slips	BAS wages reconciliation (W1/W2), STP finalisation, Payroll Tax, Tax Planning, super compliance

Reference data

Xero reference data	Used in
Tax Rates	GST type classification for risk engine rules
Chart of Accounts	Account type classification, balance sheet detection
Organisation	ABN + legal name for auto-matching

Caching: Reference data (Tax Rates, Chart of Accounts) is cached for 30 minutes and reports for 3 minutes, to stay inside Xero’s rate limits. Payroll and the general-ledger journals are kept in a copy that OneHQ tops up from Xero as you open the views that use them — payroll is refreshed in the background once that copy is more than 30 minutes old. Everything else is fetched live each time you view it.

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 showing Xero readiness data

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.

Year-end review

Beyond the job screens, OneHQ reads the same ledger to do the year-end work: Review lists the transactions and journals an accountant would question and prepares the reclassifying journals, Bank Rec and BAS & ATO reconciliation tie the ledger to the bank and the ATO, and the workpaper pack prints the lot. Every figure is live from Xero; a journal reaches Xero only when a person in your practice posts it.

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 showing Xero readiness signals

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 year-end review screens show a “Connect Xero” state instead of the ledger

BAS job detail for a client with no Xero organisation linked

BAS job detail with no Xero organisation linked — the reconciliation panels stay empty and Financials asks you to link one, instead of showing 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 showing Xero connection status

Client record — the Connections card shows whether the entity is linked to a Xero organisation, with an option to connect it when it isn’t.

All Xero connection settings are in Settings > Xero Connections. From the Client organisations list you can:

View all connected Xero organisations, who holds each connection, and their mapped entities
Change entity mappings via the client picker on each row
Connect additional Xero organisations (“Connect to Xero” button under the list)
Refresh the list of available organisations (“Refresh” button)
Reconnect an organisation OneHQ can no longer read (“Reconnect” on its row)
Disconnect individual organisations

Xero deep-links

When an entity is linked, OneHQ records the organisation’s Xero short code automatically and shows “Open in Xero” on the client’s Connections card and on job detail pages. These open the relevant Xero page for that organisation directly in your browser.

Risk engine configuration

The risk engine analyses BAS readiness data from Xero on its Standard settings — balanced materiality floors and scaling, recommended for most practices. The settings in use are shown beside the materiality floor on the BAS job.

Disconnecting Xero

You disconnect Xero organisations one at a time.

Disconnect a single organisation

Go to Settings > Xero Connections
Click the “Disconnect” button on the specific organisation row
Confirm the disconnection

This revokes OAuth access for that single organisation for everyone in your practice, unlinks any entities mapped to it, deletes OneHQ’s stored copies of its Xero data, and removes it from your available connections. Other Xero organisations remain connected.

After disconnecting, any BAS readiness, tax return, and tax planning views will lose access to Xero data. Jobs and entity records are not affected — only the live financial data feeds stop. You can reconnect at any time to restore access.

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. OneHQ then lists the affected organisations that are linked to a client under “Needs attention” in Settings > Xero Connections once Xero refuses its requests — unlink or disconnect them there to keep things clean.

Frequently asked questions

Does OneHQ write any data back to Xero?

Only when a person asks it to. OneHQ reads your ledger for analysis and reporting, and writes to it only at your direction: Review prepares manual journals that you check and then post, revise or reverse; you can recode a transaction, record a bank transaction from a OneHQ tool, and add or archive the accounts a journal needs; and you can approve a draft invoice in your firm’s own Xero organisation for Xero to send. It never creates an invoice, never records time, never creates or modifies bank feeds or pay runs, and never writes without a user action.

How often does data sync from Xero?

You always see the latest figures — OneHQ pulls them from Xero as you open each job, financial view or compliance check, so there’s no stale overnight copy to worry about.

Reference data like Tax Rates and the Chart of Accounts is cached for 30 minutes, and reports (P&L, Balance Sheet) for 3 minutes, to reduce API calls. Payroll and the general-ledger journals are kept in a copy OneHQ tops up from Xero as you open them; payroll is refreshed once that copy is more than 30 minutes old. Transactions are fetched live each time.

What Xero permissions does OneHQ request?

OneHQ requests these read scopes:

accounting.contacts.read — contact information
accounting.payments.read — payments
accounting.journals.read — journal entries
accounting.reports.read, with the individual report scopes (profit and loss, balance sheet, trial balance, bank summary, tax, aged and executive summary reports) — P&L, Balance Sheet, Trial Balance, Bank Summary, published BAS/GST
accounting.attachments.read and accounting.budgets.read — attachments and budgets
payroll.payruns.read and payroll.payslip.read — pay runs and pay slips
payroll.employees.read — employees
payroll.settings.read — payroll configuration

And these write scopes, for the actions described above (each also lets OneHQ read what it covers):

accounting.settings — read the chart of accounts, tax rates and organisation info, set up the accounts a journal posts to, and archive or restore an account you reclassify
accounting.manualjournals — create, update, post, reverse and void the journals Review prepares
accounting.banktransactions — read bank transactions, and recode one where you ask OneHQ to
accounting.invoices — read invoices, and approve a draft invoice and ask Xero to send it (only ever in your firm’s own Xero organisation, never a client’s)

Every write is initiated by a user in your practice. OneHQ does not alter a ledger on its own.

How do I disconnect from Xero?

Go to Settings > Xero Connections and click “Disconnect” on the organisation’s row. Organisations are disconnected one at a time. Disconnecting revokes OAuth access and unlinks entities from that Xero org.

See the Disconnecting Xero section above for full details.

Why can’t I see financial data for an entity?

Financial data only appears when an entity is linked to a Xero organisation. Check that:

Your practice has a Xero connection (Settings > Xero Connections)
The entity is mapped to a specific Xero organisation (check the client’s record under Connections, or Settings > Xero Connections)
OneHQ can still read the organisation (in Settings > Xero Connections, an organisation under “Needs attention” has a “Reconnect” button)

Does OneHQ appear on my Xero invoices or affect my Xero subscription?

No. OneHQ is a separate product with its own subscription. Connecting OneHQ to Xero does not add any charges to your Xero subscription, create any Xero invoices, or appear on your Xero bill. The OneHQ integration appears as a connected app in your Xero settings (under Connected Apps), but that’s purely for managing access — it doesn’t affect billing.

Can I reconcile bank accounts from OneHQ?

No. OneHQ reads reconciliation status from Xero (whether accounts are reconciled for a period), but actual reconciliation must be done in Xero. OneHQ’s BAS readiness check will flag if bank accounts are unreconciled for the BAS period so you can address it in Xero before lodging.

What happens to my data if I disconnect Xero?

Disconnecting removes the live Xero data feeds and deletes OneHQ’s stored copies of that organisation’s Xero data. Your jobs, entities, communications, and all other OneHQ data remain untouched. Only the views that pull live financial data (BAS readiness, tax return readiness) will show “Not Connected” states instead of Xero data.

You can reconnect at any time to restore access.

Can multiple staff members connect their own Xero accounts?

Yes. Each staff member can connect their own Xero account. OneHQ aggregates all connected organisations across all staff in the practice. This is useful when different team members have access to different Xero clients.

What are the Xero API scopes and limitations?

OneHQ does not support the following Xero features (they are outside the integration scope):

Creating invoices from scratch (OneHQ can approve and send a draft you already have, in your firm’s own Xero organisation only)
Modifying or creating contacts
Bank feed management or reconciliation
Creating or modifying pay runs
Managing Xero settings generally (OneHQ reads the chart of accounts, sets up only the accounts a journal needs, and archives or restores an account only when you reclassify it)
Fixed asset management
File/attachment uploads to Xero

The integration is purpose-built for Australian accounting compliance workflows — BAS, tax returns, and tax planning. These are the workflows where Xero data adds the most value.

Troubleshooting

“No Xero connection” appears even though I’m connected

This usually means the entity is not linked to a Xero organisation. Being connected to Xero at the practice level isn’t enough — each entity needs to be mapped to a specific Xero org.

Open the client’s record and check the Connections card. If the Xero row offers “Connect”, click it and select the correct Xero organisation.

If OneHQ can no longer read the organisation (for example, its Xero access was revoked), go to Settings > Xero Connections — it is listed under “Needs attention” — and click “Reconnect” on its row.

ABN auto-matching didn’t link my entities

ABN auto-matching requires that:

The entity has an ABN in OneHQ (it comes across from the client’s Business Number in XPM)
The Xero organisation has a matching ABN set in its Xero Settings > Organisation Details
The entity isn’t already linked to another Xero org
No other entity in OneHQ carries the same ABN
The organisation was newly connected — matching runs when an organisation is first connected

If ABNs match but weren’t linked at connection time, link them yourself: in Settings > Xero Connections, choose the “Not linked” filter and pick the client on each row.

Xero data seems outdated

OneHQ fetches data from Xero each time you open a view, but some of it is held briefly to stay inside Xero’s rate limits: reports for up to 3 minutes, Tax Rates and Chart of Accounts for 30 minutes, and payroll is refreshed once OneHQ’s copy is more than 30 minutes old.

If you’ve just made changes in Xero and don’t see them reflected:

Wait a few minutes, then close and reopen the job detail or financial view to trigger a fresh fetch
Wait up to 30 minutes if the issue is with tax rates, accounts or payroll
Check that the changes are saved and finalised in Xero (draft transactions may not appear)

I’m getting rate limit errors

Xero has API rate limits (60 calls per minute per tenant, 5 concurrent requests). OneHQ handles rate limiting automatically with retry logic. If you hit limits:

Wait a minute and try again
Avoid opening multiple job details for the same client simultaneously
If the issue persists, contact us — there may be another app consuming your Xero API quota