Connect Xero banking and view categorised transactions
The Xero banking feed imports read-only spend, receive and invoice payment transactions from Xero. You can view category cash totals by month, link Xero bank accounts to existing Hub accounts, and see a combined ledger alongside your manual entries. The feed is separate from your Hub manual bank ledger and does not create manual bank accounts, settle invoices, update budget actuals automatically or change cash balances. Imported Xero cash can however be selected as a **budget actuals source** — see *Track actuals automatically*. ## Before you begin - Your Xero connection must already be active in **Settings → Integrations → Xero**. - The Finance module must be enabled in your workspace. - You must be a workspace owner or administrator with Finance access. - Existing connections need a fresh reconnect to grant the required read-only bank transaction and bank balance scopes. ## Enable banking sync 1. Open **Settings → Integrations**. 2. Find the **Xero** row and expand it. 3. If the **Banking sync** section shows *Reconnect Xero for banking access*, select **Reconnect Xero** and approve the read-only bank transaction access when prompted. 4. Once banking access is available, select **Enable banking sync**. The feed imports spend and receive transactions and invoice or credit-note payments from the history date configured in your Xero settings. Imports process in batches every 15 minutes. A large initial history may take several jobs to complete. ## Xero read allowance Xero limits how many API reads Hub can perform. If the daily or per-minute limit is reached, Hub records a **delayed** status and pauses banking sync until the allowance resets. The reset time (minute or day) is shown in the sync status. Imported records remain available and are not lost during a delay. Sync resumes automatically when the allowance resets. ## View Xero transactions 1. Open **Banking** in your workspace. 2. Select the **Xero transactions** tab. The view shows monthly category cash totals for the selected currency. Select a month and currency to filter the results. Category figures include tax and allocate invoice payment amounts proportionally across the invoice's line categories. These are cash-basis figures and may differ from Xero's accrual profit and loss. **What is excluded from category totals:** - Transfers, prepayments and overpayments. - Deleted or voided entries. - Entries outside your configured history start date. - Entries with sync errors (shown as issues to review). - Foreign currency entries when a specific currency is selected. - Uncoded statement lines. The monthly view loads up to 2,000 entries. Months with more than 2,000 entries are labelled as partial — do not use a partial month as a complete budget baseline. Entries not yet reconciled in Xero are flagged in the view. Reconcile them in Xero, then sync Hub before treating totals as confirmed bank spending. ## Sync status and coverage The Xero transactions view shows: - **Status** — the current sync state (Disabled, Paused, Delayed, syncing, needs-attention, or idle). - **Last read** — when the most recent sync job ran. - **History from** — the date from which transactions are imported. - **Imported records** — the total count of saved Xero entries. - **Last batch** — how many entries were checked, updated, and skipped before the history start date in the most recent job. If coverage is incomplete or import issues are present, a warning is shown. Do not use category totals as a complete budget baseline until a full scan has completed and all import issues are resolved. **Paused status:** If your Xero connection is paused, imported records remain available but may be out of date. Resume the connection in Sync settings. **Delayed status:** The Xero read allowance is temporarily exhausted. Hub will retry automatically when the allowance resets. Imported records are not affected. ## Link Xero bank accounts Linking a Xero bank account to a Hub bank account lets you view imported and manual transactions together in a combined ledger. Hub also supports linking **historical Xero bank accounts** that are no longer active in Xero — these are discovered from imported transactions and can be linked to their corresponding Hub accounts. 1. Open **Banking → Xero transactions**. 2. Find the **Link Xero bank accounts** section. 3. Select **Load Xero accounts** to fetch active and historical bank accounts from your connected organisation. 4. For each Xero account: - Choose an existing same-currency Hub account from the dropdown, or leave it set to *Create a new Hub account*. - Select **Link account**. Each Xero bank account can be linked to only one Hub account, and each Hub account can be linked to only one Xero account. Existing manual entries and opening balances are not changed when you link an account. ## View the combined ledger Opening a linked bank account shows its Xero imported entries and manual entries together. - **Matched entries** appear once, using Xero's amount with the manual entry's notes and budget references retained. - **Unmatched entries** appear separately until matched. - Entries with changed or unavailable sources are flagged for review. - You can **filter by date range, direction and reconciliation status**, and **sort by date, amount or description**. To match a Xero entry to a manual entry, select the manual entry from the dropdown on the Xero row and confirm. Matching is reversible. Amounts, currency and direction must agree; otherwise, resolve the difference before matching. The ledger displays up to 10,000 Xero entries. If there are more, a partial warning is shown. ## Xero bank balances For linked accounts, Hub fetches a dated balance from Xero's Bank Summary report during each sync. The combined ledger shows: - **Balance in Xero** — the balance as of the last successful snapshot, with the date and the time it was read. - A warning if the balance snapshot is unavailable or if the last refresh failed. The balance reflects Xero's accounting view of the account. Unreconciled bank statement entries may cause the bank's own balance to differ. Manual ledger totals are shown separately and are not added to the Xero balance. The bank accounts list shows the Xero balance (with date) for linked accounts instead of the manual ledger total. The list total for linked accounts is labelled **Recorded balances** and reflects Xero snapshots where available. To compare the accounting balance with the available bank cash, use **Verify available cash** in Cash flow to record dated bank evidence. See *Review cash and manage commitments*. **If the balance shows as unavailable:** Your connection may not have the Bank Summary read scope. Use **Reconnect Xero** in Sync settings and approve the read-only Bank Summary access. ## Use Xero cash as a budget actuals source Once the Xero banking feed is active and your accounts are linked, you can connect a budget line to Xero cash movements as its actuals source: 1. Open the budget and click a line name to open its settings. 2. Under **Actuals source**, choose **Xero cash actuals**. 3. Choose the **Xero organisation**, an optional **bank account** filter, a **measure** (cash out, cash in, or net), and the **Xero categories** to include. 4. Save the mapping. Mappings are previewed before saving. Overlapping category selections across lines in the same budget block calculation — resolve overlaps before the source can confirm actuals. Xero cash actuals require Finance administrator access. Figures are incomplete for any period before the history start date or before an initial complete scan. For full details on all actuals source types, see *Track actuals automatically*. ## What does not change - Manual bank accounts, bank transactions and opening balances are not created or modified by the banking feed. - The Xero feed does not settle Hub invoices, alter settlement links or update budget actuals directly (actuals are calculated at read time from imported movements). - Xero entries are never added to your manual ledger balance. ## Troubleshooting **Banking sync shows *Reconnect Xero for banking access*.** The existing connection does not include read-only bank transaction access. Select **Reconnect Xero** and approve the banking scope when prompted. **Xero balance shows *Awaiting Xero bank summary* or a warning.** The connection may be missing the Bank Summary read scope. Use **Reconnect Xero** in Sync settings. **Category totals are incomplete or a month is labelled partial.** The initial scan may still be running, or the 2,000-entry limit was reached. Check the imported records count and last batch details. Resolve any import issues shown in the issues list. **Sync status shows Delayed.** The Xero read allowance is exhausted. Hub will retry automatically. The reset time is shown in the sync status. No action is required; imported records remain available. **A linked account shows *Xero balance pending*.** The balance snapshot has not yet been fetched for this account. Wait for the next sync job to complete. **Matching is rejected with an *amounts must agree* error.** The Xero entry and manual entry amounts, currency or direction do not match. Check both entries and correct the discrepancy before matching. **Budget actuals show Incomplete source for a Xero cash line.** The history import may not yet be complete, or the selected categories overlap with another line. Open the **Source review** disclosure in the budget for details. See *Track actuals automatically* for the full list of Xero cash actuals requirements.