Connect Xero

Connect the Xero organisations whose finance data you want to use with your assistant. The connection belongs to the current xpnAI Workspace and supplies data to its members.

Before you begin

• Check that the Workspace shown in the product header is the one you intend to use.
• Have a Xero account that can authorise access to the required organisations. If Xero does not let you authorise an organisation, ask the person who manages its Xero access.
• Make sure your xpnAI trial or subscription allows changes. If billing needs attention, ask a Subscription Administrator to resolve it.

Only a Workspace Administrator can authorise Xero, choose organisations, add or reconnect access, disconnect a connection or delete imported data. Any Workspace member can use Sync now for an enabled organisation and Sync all. During initial Workspace setup, a Workspace Administrator or a Subscription Administrator can complete the connection and selection steps. Inviting someone else to connect Xero needs Subscription Administrator authority. Once the first import is queued, setup can continue while the data is prepared.

1. Authorise access in Xero

1. In xpnAI, open Connections > Xero. You must be a Workspace Administrator to connect Xero.
2. Select Connect to Xero.
3. Sign in to Xero if prompted. Review the organisations and requested access, then complete Xero’s authorisation.
4. Return to xpnAI. The Choose organisations picker opens.

During first-Workspace setup, the Connect to Xero button starts the same authorisation process. If someone else manages your Xero, Someone else manages our Xero invites them as a Workspace Administrator to finish the step, and a Workspace Administrator can complete the Xero steps of setup.

Xero asks for access to finance data and permissions that support changes, including accounting settings, payments and manual journals. An assistant can make only the changes supported by xpnAI and included in the permissions you grant when connecting that assistant. Draft journals must still be reviewed and posted by you in Xero.

If the authorisation expires or fails, ask a Workspace Administrator to return to Connections > Xero and select Connect to Xero again.

2. Choose what to import

1. In Choose organisations, select each organisation this Workspace should use.
2. Select Save selection.
3. Check that the selected organisations appear under Sync enabled. Their data imports in the background.
4. During first-Workspace setup, select Open Workspace as soon as the first sync is queued. You can invite your team and manage Workspace settings while the data is prepared. Finance data queries remain unavailable until the first sync completes and the Organisation is Ready. The notice tells you whether xpnAI will email you or the user who connected the Organisation after its first sync completes; it does not show an email address.

Available lists organisations authorised in Xero but not selected for sync. Sync enabled lists organisations selected to sync with this Workspace, including those that need reconnecting. Authorisation grants access; selecting an organisation enables importing its finance data.

To add an already authorised organisation later, a Workspace Administrator can select the plus icon, Add sync, beside it under Available. To add an organisation that is not listed, a Workspace Administrator must select Connect to Xero and authorise it first. Members can select Sync now for organisations already under Sync enabled and Sync all above the list.

To check connection costs and your included allowance, open Administration → Users & Billing → Billing. Disconnecting keeps retained imported data counted until you delete it.

Row actions use icons. Circular arrows mean Sync now, a link means Reconnect, a broken link means Disconnect, and the delete icon means Delete data. Hover over an icon to read what the action does.

For optional journal or chart changes, the assistant uses the destination organisation specified in your request. The reporting selection does not choose that destination. Always name the organisation when asking for a change.

3. Check the first import

Imported manual journal line descriptions retain up to 500 characters. Longer descriptions are shortened in xpnAI; the original description in Xero is unchanged.

If a journal or invoice refers to a tracking option that is unavailable in the imported tracking categories, xpnAI skips that tracking assignment. The transaction and its amounts still import, along with any available tracking assignments.

While an organisation is importing, its row shows the current stage, such as Importing journals. Select Current sync beneath its name to see counts for each available type in the current import group, elapsed time and the last progress update. After a sync finishes or fails, this link is called Last sync. During first-Workspace setup, each organisation shows a bar with one segment per import step and the current step number, and Sync details expands the progress. You can select Open Workspace as soon as the first sync is queued; imported data remains incomplete until the first sync finishes and the organisation is Ready. On the Connections page, the first import shows First run - Running for …. Hover over the running time for the first-sync guidance and email notification details. Select the question-mark icon beside it to open this guide. The current progress and recovery actions remain available while the import continues.

The first three detail groups show Imported, Importing, or Waiting as the work moves through the import. The final group is Final checks and shows Waiting, In progress, or Complete. A group is marked Imported only after all of its data is saved.

After a successful sync, Final checks shows Complete and the progress-update footer is removed.

The large figures follow the current group. Organisation and reference data shows tracking categories, accounts, asset types and contacts. Journals shows journals, journal lines, manual journals and manual journal lines. Invoices and other transactions shows invoices, bank transactions, assets, credit notes, prepayments, overpayments, payments and deleted payments. Counts appear when available and wrap onto more lines when needed.

For both the first import and later incremental syncs, these figures count each record once during that sync. They include additions and updates to existing records, as well as unchanged records returned by Xero. Resuming a paused or failed sync keeps its counts without counting repeated records again. After completion, each group is collapsed to a Stored (last sync) summary. Group totals include journal and manual journal lines as individual records, matching the overall stored total. Expand a group to see its record types in Stored and Last sync columns. The last-sync count includes updates and unchanged records processed during that sync. After a successful sync, the large figures show Total records stored across these types, including journal and manual journal lines, and Last sync duration. Final checks also shows the stored total while the sync finishes. If a sync stops, the duration shows how long it ran before stopping.

If Xero’s request limit pauses the import, the current group shows Paused with the resume time. xpnAI keeps the saved progress while it waits, so you can leave the page. If an import fails, open its details to read the Xero error before selecting Sync now or Retry.

xpnAI renews Xero access automatically while a sync is running, including long imports. You only need to reconnect when Xero no longer accepts the renewed access or the authorisation cannot be renewed.

The last successful sync time tells you how current the imported data is. Recent syncs show Today or Yesterday with the time, read in the Workspace time zone. Hover over the timestamp to see the full date, time including seconds, and the name of that time zone. A failed or waiting import does not make older data current.

If final checks need exchange rates that are missing, xpnAI imports month-end and monthly average rates for the affected currencies and months, then retries the calculation automatically. You do not need to import these rates yourself. If the sync still fails, read the error before retrying or contacting support.

Check sync health from any page

The status above Help in the sidebar summarises sync-enabled Xero connections in your current Workspace. Hover over it for details, or select it to open Connections > Xero.

Sidebar sections expand independently, so you can keep Connections and Administration open together. A down chevron marks an expanded section.

• Healthy, green: all selected connections have synced successfully, with no outstanding sync error or wait for Xero.
• Syncing: a connection is preparing its first sync, including queued or resumed work.
• Waiting, neutral: a connection is waiting for Xero or has not started its first sync, with no failed or disconnected connections.
• Partial, orange: some selected connections have failed or need reconnecting.
• Failed, red: all selected connections have failed or need reconnecting.

Inactive means no connections are enabled for sync. Checking appears while loading, and Unknown means the status could not be checked. These states use a neutral dot.

If the Connections page temporarily cannot refresh progress, it keeps the last known organisation status and shows Sync status unavailable. The notice clears automatically when a later refresh succeeds.

Health refreshes automatically. A successful connection stays healthy between scheduled imports and while its next import runs. Health describes sync outcomes; check the last successful sync time to see how current the data is.

Keep data up to date

xpnAI automatically refreshes selected, connected organisations hourly. Hover over the description under Sync enabled to see the timing.

To refresh immediately, select Sync now beside one organisation or Sync all above the list. The next automatic refresh keeps its scheduled time. If an import is already running, wait for it to finish.

To pause automatic refreshes, select the description under Sync enabled, then Pause. When paused, this description shows that automatic hourly sync is paused. Select it and choose Resume to restart automatic refreshes. Sync all still works while automatic refreshes are paused.

If a recent Xero transaction is missing from your assistant’s results, refresh the organisation and ask the assistant to retrieve the data again after the successful sync time updates.

Disconnect or delete imported data

On the organisation’s row, a Workspace Administrator can hover over the action icons to find Disconnect or Delete data. Select the action and read the confirmation before continuing. Members can see the connection status and sync actions but cannot change the connection.

• Disconnect removes Xero access. A sync-enabled organisation stays under Sync enabled as Disconnected, with its imported data kept and counted toward the Workspace’s connection total. Reconnect it to resume syncing.
• Delete data disconnects the organisation if needed and permanently removes its imported data and mappings from this Workspace. It does not delete the original records in Xero.

You can delete a disconnected organisation’s imported data without reconnecting it. Missing or expired authorisation also allows local cleanup. If Xero returns another error while refreshing access or disconnecting an active organisation, xpnAI keeps its imported data and shows an error. Try again; if you changed access in Xero, refresh the page before retrying.

If the connection changes while the action is running, xpnAI stops local cleanup. Refresh the page to see the current connection before trying again.

Organisations under Available have Add sync and Disconnect for Workspace Administrators. Disconnecting removes them from the list. They also disappear when Xero no longer grants access. Deleting a sync-enabled organisation removes it from both sections.

An organisation that has never been imported and is not enabled for sync does not block assistant queries for your synced organisations. If an organisation has a partially imported dataset, complete its first sync before querying that retained data.

Deleted data cannot be restored within xpnAI. A Workspace Administrator can import the organisation again by authorising it through Connect to Xero and selecting it for the Workspace.

If you cannot connect

If Connect to Xero is unavailable because you are a Member, ask a Workspace Administrator to make the connection change. If it is disabled and the page says Xero is not configured, contact xpnAI support. There is no connection setting for you to fix on this page.

If Xero access has expired or an assistant reports missing permission for a journal or account change, authorise Xero again. Also check the permissions granted to the assistant in Connect an MCP client.