Documentation · Integrations
Connect Xero
Connect a Xero organization to LiteHQ: authorize via OAuth, pair organizations to locations, choose what syncs (invoices, payments, reconciliation), and reconnect.
LiteHQ can push your tenant invoices into Xero and help your Stripe payouts reconcile cleanly, so your accounting reflects what happened in the workspace without manual double entry. This guide walks an operator (host) through connecting a Xero organization, choosing exactly what syncs, pairing organizations to locations if you run more than one, and recovering when a connection goes stale.
It is also honest about the edges. Some pieces are fully automatic (invoice push, token refresh) and some are deliberately not (the Xero Stripe feed is a one-time manual Xero step, and reconciling individual Stripe charges still needs a quick Find and Match inside Xero). Where a step happens outside LiteHQ, this guide says so.
Before you start
Connecting Xero is an operator (host) task. You need to be an admin, owner, or billing contact on the workspace: LiteHQ checks for a privileged role before it will start the Xero authorization, so a standard member cannot connect or disconnect an integration.
Xero is part of the paid LiteHQ plan. The connect flow is plan-gated, so if your workspace is on a free or suspended plan you will be prompted to upgrade before the authorization screen opens.
You will also need login access to the Xero organization you want to connect, with permission in Xero to authorize a third-party app.
- A LiteHQ admin, owner, or billing-contact login.
- A paid LiteHQ plan (the Xero connect button is gated behind it).
- Access to the Xero organization, with rights to authorize apps.
One LiteHQ workspace can hold several Xero connections: one optional Organization-level connection plus one per location. You only need as many as you run separate Xero books for.
1 · Open the Xero integration page
From the operator side of LiteHQ, go to Integrations and open Xero Accounting. The page header is Xero Accounting and it lives at /w/your-slug/integrations/xero.
At the top you will see a tab row: an Organization tab plus one tab per location you operate. The Organization tab is a central connection you can share across locations; each location tab is a separate connection for that location's own Xero book. Pick the tab you want to set up first. If you run a single space, the Organization tab is the simplest place to start.
- Organization tab: a central connection, shareable to locations.
- One tab per location: a dedicated connection per location's Xero book.
- A green Connected badge appears on a tab once that connection is live.
2 · Connect a Xero organization
On the tab you chose, click Connect New Account. LiteHQ redirects you to Xero's hosted sign-in and consent screen. Sign in to Xero, choose the organization to authorize, and approve the requested access. Xero then sends you back to LiteHQ automatically.
On the return trip LiteHQ reads which Xero organizations you authorized and decides how to map them. If you authorized exactly one organization, LiteHQ links it automatically and the tab flips to Connected. If you authorized more than one, LiteHQ either smart-matches by name (when a Xero organization name resembles the location name) or shows an Action Required panel asking you to pick which organization to link to this tab.
If the page asks you to choose, use the organization selector in the Action Required panel, confirm, and the tab moves to Connected.
- Click Connect New Account on the target tab.
- Authorize the organization in Xero's own consent screen.
- One authorized org links automatically; multiple orgs may prompt a manual selection.
- Confirm the organization if asked, then the tab shows Connected.
Starting a new connect first revokes any existing tokens for that tab, which is why Xero always shows the consent screen again rather than silently re-authorizing. This is expected.
3 · Pair organizations to locations (multi-location)
If you run more than one location, each location can point at its own Xero organization. There are two ways to wire this up.
First, the per-location tabs: open a location's tab and click Connect New Account to run a fresh authorization for that location, or use Use Existing Connection to point this location at an organization you already authorized from another tab. Reusing an existing connection is handy when several locations share a single Xero book.
Second, the Active Xero Connections panel at the top of the page lists every Xero organization you have authorized through the LiteHQ Xero app, with its Xero tenant id and where it is currently mapped. Each row has a Quick link to location selector so you can map an authorized organization to the Main Organization or to a specific location in one step. Rows that are not yet linked show an Unmapped badge.
- Per-location tab plus Connect New Account: a dedicated authorization for that location.
- Use Existing Connection: reuse an already-authorized organization for another location.
- Active Xero Connections panel: see every authorized organization and quick-link it to a location.
- Change link on a connected tab: switch a location to a different authorized organization.
Because each location typically has its own Stripe account and its own Xero organization, you set up the connection (and later, reconciliation) up to once per location.
4 · Choose what syncs
Once a tab is Connected, open the Generic and Sync tab to control the data flow. The settings here are per connection, so a multi-location setup can sync differently per location.
Sync Invoices sends LiteHQ invoices for this connection into Xero. Sync Payments enables two-way payment and reconciliation behavior. Sync Mode chooses when invoices go across: Manual (push only, you trigger it) or Automatic (on creation). Default Xero Invoice Status sets the status applied to synced invoices in Xero: Draft, Submitted (awaiting approval), or Authorised (awaiting payment).
Click Save Changes to persist. The page warns you with an Unsaved changes indicator if you navigate away with edits pending.
- Sync Invoices: push LiteHQ invoices to Xero.
- Sync Payments: enable two-way payment and reconciliation behavior.
- Sync Mode: Manual (push only) or Automatic (on creation).
- Default Xero Invoice Status: Draft, Submitted, or Authorised.
- Save Changes commits the settings for that connection.
5 · Map accounts, tax, and items
The remaining tabs map LiteHQ's internal categories onto your Xero chart of accounts so invoices land in the right ledger. None of these are strictly required to connect, but mapping them makes synced invoices accurate and saves manual recoding in Xero.
Revenue Accounts maps your internal billing codes to Xero revenue accounts. Payment Accounts maps payment methods to Xero bank accounts and lets you pick a default bank account for recording receipts. Tax Rates maps your standard, zero-rated, and exempt rates to Xero tax rates. Inventory maps bookable facilities to Xero inventory items. Branding picks which Xero invoice template to use, and Tracking Categories lets you tag synced lines.
Several mapping rows include a create-in-Xero shortcut, so if a matching revenue account, payment clearing account, or inventory item does not exist yet in Xero, LiteHQ can create one and select it for you.
- Revenue Accounts: internal billing codes to Xero revenue accounts.
- Payment Accounts: payment methods to Xero bank accounts, plus a default receipt bank account.
- Tax Rates: standard, zero, and exempt rates to Xero tax rates.
- Inventory, Branding, Tracking Categories: items, invoice template, and line tags.
- Create-in-Xero shortcuts exist on revenue, payment, and inventory rows.
Mappings are read live from the connected Xero organization, so if you add an account or item in Xero, use Refresh Settings on the page to pull the new options into the dropdowns.
6 · Reconcile Stripe payouts (optional)
If you take payment through Stripe, the Reconcile Stripe payouts card sits above the mapping tabs and helps your Stripe payout deposits reconcile in Xero without double-counting revenue. This is per location, because each location has its own Stripe account and Xero organization.
There is one manual Xero step LiteHQ cannot do for you: connecting Xero's native Stripe feed. In Xero, go to Accounting, then Bank accounts, then Add Bank Account, search for Stripe, and sign in with this location's Stripe account. Set the import start date to today so Xero does not re-import history you have already reconciled. Give Xero a minute to import.
Back in LiteHQ, click Detect Stripe account. LiteHQ finds the Stripe bank account created by the feed (and asks you to pick the right currency if there is more than one), then Turn on reconciliation. After that, your Stripe payout deposits reconcile in one click in Xero.
- Per location, alongside that location's Stripe account.
- Connect Xero's native Stripe feed in Xero first (a one-time manual step).
- Set the feed's import start date to today to avoid re-importing reconciled history.
- Click Detect Stripe account, confirm the account, then Turn on reconciliation.
Individual Stripe charges still need a quick Find and Match in Xero. Never click Create on those charge lines: the invoice already booked the revenue, so Create double-counts it.
What is and is not automated
It helps to be clear about which parts run on their own and which need a human.
Automatic: once Sync Invoices is on, invoices flow to Xero (immediately in Automatic mode, or on demand in Manual mode). LiteHQ keeps your Xero connection alive by refreshing the access token in the background, so you do not have to reconnect every hour. A background sync also keeps invoice statuses reconciled between LiteHQ and Xero.
Manual or external: connecting Xero's native Stripe feed is a one-time step you do inside Xero. Matching individual Stripe charges uses Find and Match in Xero. Picking which Xero organization links to which location is your choice when more than one is authorized. And the manual Sync Status button on the page pulls the latest invoice status from Xero on demand.
- Automatic: invoice push (per your sync mode), background token refresh, status reconciliation.
- Manual in Xero: connecting the Stripe feed, Find and Match on charges.
- Your choice in LiteHQ: organization-to-location pairing, manual Sync Status pulls.
Troubleshooting and reconnecting
Stale connection: each connected tab shows the last successful token refresh. LiteHQ refreshes tokens in the background well inside Xero's refresh window, but if a connection has not refreshed in over 7 days the page shows a Stale badge. The usual cause is a revoked or broken authorization. The fix is to reconnect: open the affected tab, Disconnect, then Connect New Account and re-authorize in Xero.
Action Required after connecting: this means you authorized more than one Xero organization and LiteHQ could not confidently pick one. Use the selector to choose the organization for that location.
Wrong organization linked: on a connected tab, click Change next to Connected to and switch to another authorized Xero organization.
Disconnecting: the Disconnect button stops syncing invoices and payments for that connection and revokes the stored tokens. You can reconnect at any time.
- Stale badge after 7 days: Disconnect, then Connect New Account to re-authorize.
- Action Required: pick the correct Xero organization in the selector.
- Wrong org: use Change next to Connected to and switch organizations.
- Disconnect stops syncing and revokes tokens; reconnect any time.
If a sync error appears, the manual Sync Status button re-pulls invoice status from Xero, and Refresh Settings reloads accounts and items from the connected organization. Most transient issues clear with one of those, or with a reconnect.
Frequently asked
Who can connect Xero?
An operator (host) with an admin, owner, or billing-contact role on the workspace. LiteHQ checks for a privileged role before starting the Xero authorization, so standard members cannot connect or disconnect it. A paid plan is also required.
Do I need a separate Xero connection per location?
Only if each location keeps its own Xero book. You can connect one Xero organization at the Organization level and share it across locations, run a dedicated connection per location tab, or mix the two. The Active Xero Connections panel lets you map any authorized organization to a location.
What gets synced to Xero?
With Sync Invoices on, LiteHQ pushes invoices to Xero, immediately in Automatic mode or on demand in Manual mode, using the default invoice status you choose (Draft, Submitted, or Authorised). Sync Payments enables two-way payment and reconciliation behavior, and a background process keeps invoice statuses reconciled between the two systems.
Why do I still have to match Stripe charges by hand in Xero?
LiteHQ connects to the Xero Stripe feed so your payout deposits reconcile in one click, but individual Stripe charge lines still need Find and Match in Xero. Use Find and Match, never Create, because the invoice already booked the revenue and Create would double-count it.
My connection shows a Stale badge. What do I do?
LiteHQ refreshes Xero tokens automatically, but if authorization was revoked or broke, a connection can go stale after about 7 days. Reconnect: on the affected tab, click Disconnect, then Connect New Account, and re-authorize in Xero.
It says Action Required after I connected. Why?
You authorized more than one Xero organization and LiteHQ could not confidently pick which one belongs to this location. Use the organization selector in the Action Required panel to choose, and the tab will move to Connected.