The Xero integration connects your MSP's billing to its books. AlgaPSA exports finalized invoices to a connected Xero organisation and reads back payments, credit-note allocations, and invoice changes. Your billing team can check what a client still owes without re-entering payments recorded by accounting in Xero.

For example, GreenLeaf Dental Group buys monthly managed endpoint care. Map that service to the correct Xero item or revenue account, export its finalized invoice, and record the client's payment in Xero. The next successful sync applies the payment to the linked AlgaPSA invoice. Check the organisation, invoice total, and remaining balance before treating the billing period as reconciled.

This guide covers connection, mappings, and ongoing checks. For the wider workflow, see 14.14. How Accounting Works in AlgaPSA: Invoices, Payments, Credits, and Your Books. The manual Xero CSV workflow remains available in 14.17. Export Finalized MSP Invoices for Import into QuickBooks, Xero, and Other Accounting Systems.

What the Xero integration does

Two-way sync does not mean every action travels in both directions. Use this table when deciding where your accounting team should record a change.

Record or action	Direction	What happens
Finalized invoices	AlgaPSA to Xero	Invoice exports use the service and tax mappings for the selected Xero connection.
Finalized credit notes created in AlgaPSA	No automatic Xero credit-note creation	Do not rely on invoice export to create a credit note in Xero. Arrange the corresponding entry with accounting and verify it in Xero.
Payments recorded in Xero	Xero to AlgaPSA	Payments apply to the linked AlgaPSA invoice once, updating its balance and payment status. Replaying a sync does not apply the money again.
Credit notes recorded in Xero	Xero to AlgaPSA	Credit-note changes are read, and allocations against linked invoices reconcile through the payment ledger. This does not import every historical Xero credit note as a new AlgaPSA billing document.
Payment reversals and replacements in Xero	Xero to AlgaPSA	Reversals reconcile with the earlier payment. A replacement payment that settles the same invoice preserves the correct net balance.
Invoice total or number changed in Xero	Xero to AlgaPSA	AlgaPSA flags drift from the exported document without rewriting its invoice lines.
Payments made in AlgaPSA, including Stripe and manual payments	AlgaPSA to Xero: unsupported	They are not pushed to Xero. The sync records an unsupported-operation exception instead of silently skipping the queued action.
Credits applied in AlgaPSA	AlgaPSA to Xero: unsupported	Credit applications are not pushed to Xero and are recorded as unsupported operations.
Voids made in AlgaPSA	AlgaPSA to Xero: unsupported	The Xero invoice is not voided automatically. The sync records the unsupported operation for review.

Plan a separate accounting step for unsupported outbound actions. Granting additional permissions does not add an unsupported Xero operation.

Prerequisites

AlgaPSA accounting permissions. Connection setup requires permission to manage accounting connections. Mapping and export work use separate permissions, listed below.
A Xero organisation. Use a Xero login that can authorize access to the organisation your MSP bills through.
Xero app credentials. If credentials are not already available, obtain the app's Client ID and Client Secret from your Xero app administrator. Register the exact Redirect URI shown in AlgaPSA for that app.
Mapping choices in Xero. Identify the items or revenue accounts and tax types your invoices should use. An organisation without Products & Services items can use revenue-account mappings.

Accounting permissions

Admin and Finance are the default accounting roles, with different responsibilities. The five permissions use the accounting_integrations resource. Custom roles need the specific permission for each task.

Permission	What it allows	Default roles
`accounting_integrations:catalog_read`	Read remote accounting catalogs, connection status, and sync health.	Admin, Finance
`accounting_integrations:connections_manage`	Save OAuth credentials, connect or disconnect, choose the default company or organisation, and manage sync settings.	Admin
`accounting_integrations:mappings_manage`	Create, update, retarget, and reconcile accounting mappings.	Admin, Finance
`accounting_integrations:exports_execute`	Create and execute accounting exports and run Sync Now.	Admin, Finance
`accounting_integrations:remote_mutate`	Perform supported destructive or money-moving operations in the connected accounting system.	Admin

Settings screens hide controls the user cannot use or show them as unavailable with permission guidance. Accounting Exports navigation and controls are hidden without exports_execute; a direct link shows an access-denied message. An export operator can load the export dialog's connection choices with exports_execute without also needing catalog_read.

Step 1: Open the Xero settings

Navigate to Settings > General in the sidebar to open Admin Settings.
Select Integrations under Data & Integration, then open Accounting.
Select Xero and click Configure. If another integration is already open, use Choose another first.

The panel includes Xero connection, Xero app credentials, and Live Xero Mapping & Configuration. A connected organisation also has a Xero sync activity card for health and sync controls.

Figure 1: The Xero panel before the first organisation is connected.

Step 2: Configure the Xero app and connect

Open Xero app setup details in the Xero app credentials card. Give its Redirect URI to the administrator registering your Xero app, and review Permissions requested from Xero.
If credentials are needed, enter Client ID and Client Secret, then click Save Xero Credentials. The card confirms Credentials saved. If credentials are already available, continue to the connection step.
Click Connect Xero, sign in to Xero, and authorize the organisation or organisations you intend to link.
Return to AlgaPSA in the same browser session. Confirm the linked organisations and the one marked Default for sync on Xero connection.

Start authorization from AlgaPSA each time. The callback checks the signed-in user, workspace, current connection-management permission, and a single-use connection request before saving credentials. An expired, reused, or mismatched request must be restarted. The OAuth verification secret stays on the server, and provider error details are redacted in logs and export diagnostics.

Permissions requested from Xero

Xero OAuth permissions are separate from AlgaPSA role permissions. The default request is limited to the integration's current needs:

Xero scope	Purpose
`offline_access`	Refresh the authorization for background sync.
`accounting.settings.read`	Read accounting configuration used by mappings.
`accounting.invoices`	Read invoice and credit-note changes and write exported invoices.
`accounting.payments.read`	Read payments recorded in Xero.
`accounting.contacts`	Read and maintain the contacts needed for invoice export.

Check the scopes displayed in your installation, especially if its administrator has configured an OAuth scope override. A token refresh retains the permissions granted at the last authorization. Reconnect to grant new permissions.

Step 3: Confirm status and choose the organisation

Read the connection message as well as its badge. Saved app credentials alone do not establish a usable connection.

Connection result	What to do
Connected, with the expected default organisation	Continue to mappings. Confirm the name before exporting.
Missing scope, including invoice-write permission `accounting.invoices`	Reauthorize Xero with the requested permissions. Refreshing the existing token cannot add invoice-write access.
Connection expired or Reconnect required	Use Reconnect Xero. An expired or rejected refresh token needs fresh authorization; sync and exports remain paused until it is restored.
Ambiguous saved organisation or connection	Make an explicit connection choice before syncing, mapping, or exporting. AlgaPSA refuses to guess which connection the saved selection means.
Disconnect in progress	Complete or retry the disconnect before reconnecting.

With two linked Xero organisations, review Xero organisations in the Xero sync activity card. Use Make default beside the intended organisation. The selected default supplies the context for interactive sync, exports, catalogs, and mappings. Review the organisation shown on the mapping card after changing it.

An ambiguous saved selection is a blocking error, not permission to use whichever organisation appears first. For a manual export, explicitly choose the intended connection in Target Company (Realm). If the settings panel cannot offer a usable default choice, have the accounting connection administrator resolve the connection before configuring mappings or running sync.

Step 4: Map services and tax types

Open Live Xero Mapping & Configuration and check its organisation name first.

On Items / Services, click Add Service Mapping.
Choose the Alga Service. The mapping pickers are searchable, so type a name or code to narrow the options.
Set Map To to the appropriate target type, then select the record in Xero Item or Account.
Click Save Mapping. AlgaPSA validates the target against the connected organisation.
On Tax Codes, use Add Tax Code Mapping to map each Alga Tax Region to its Xero Tax Type.

Map To	Use it when	Exported line
Xero Item	The service has a usable item in Xero's Products & Services catalog.	Carries that item's code.
Xero Revenue Account	Your accountant invoices directly to a revenue account, including organisations with no items.	Carries the account code without requiring an item code.

Item codes and account codes are different identifiers, even if their text is identical. An invalid item mapping does not automatically become an account mapping. Choose the target type explicitly and save a valid record from the connected organisation.

For GreenLeaf Dental Group's managed endpoint care, choose Xero Revenue Account if accounting posts that service directly to a managed-services revenue account. Confirm the exported line uses the intended account and tax type before the next billing run.

Mappings belong to the exact Xero connection they were saved against. A matching code from another organisation does not qualify. Older mappings without a company or connection assignment are held for review rather than guessed; review and re-save them for the intended connection before retrying an export.

Step 5: Export and verify the first invoice

Finalize an invoice whose service and tax mappings you have checked.
Open Billing > Tracking & Reports > Accounting Exports, or click Open Accounting Exports from the Xero settings.
Click New Export and choose Xero as the Adapter for live delivery. Choose Xero CSV only for a manual file import.
Set the invoice date range and optional client filter. If Target Company (Realm) appears, choose the intended Xero connection.
Click Create Batch, review the batch, and use Execute. Check the result and any errors, then confirm the invoice and line mappings in Xero.

The dialog lists only connections for the selected live adapter. Switching from QuickBooks Online to Xero clears the QuickBooks choice and loads Xero connections. File adapters need no live connection. Create Batch remains unavailable while connection choices are loading or unresolved; use Retry if loading fails. An ambiguous Xero choice requires a deliberate selection.

The full batch workflow is in 14.17. Export Finalized MSP Invoices for Import into QuickBooks, Xero, and Other Accounting Systems.

Ongoing sync, payments, and drift

Use Sync Now on Xero sync activity to run a cycle immediately. Automatic sync controls scheduled cycles, which run every 15 minutes when on. Sync Now, health, and status follow the connected provider and selected organisation, including when both Xero and QuickBooks are connected.

The sync polls Xero for invoice, payment, and credit-note changes. It applies payments and credit allocations to linked invoices exactly once. Replays do not duplicate them, and reversals, removed credit allocations, and replacement payments reconcile the earlier entries when Xero reports those changes. A failed or incomplete poll preserves its position for a later retry.

If the Xero invoice total or number differs from what AlgaPSA exported, the sync flags Drift. It does not rewrite your AlgaPSA invoice lines. Compare the two documents and resolve the discrepancy with accounting before assuming the period is reconciled.

Health check	What to look for
Most recent sync	A recent completion with no failed-operation or incomplete-sync message.
Pending ops and Errored ops	Work waiting to run or requiring attention. Unsupported outbound actions need review, not repeated attempts to make Xero accept them.
Drift and Open exceptions	Changed exported documents or reconciliation issues that accounting must investigate.
Authorization status	Reconnect guidance if the grant expires or token refresh is rejected.

Outstanding counts appear when there is work to review. After recording a payment in Xero, verify the linked AlgaPSA invoice balance. If a payment is reversed and replaced, check the net balance after reconciliation, especially when the replacement fully settles the invoice.

Disconnect and reconnect

Reconnect Xero and disconnect apply to every organisation covered by the authorization. Review the linked-organisation list before changing the connection.

Click Disconnect Xero, or Disconnect all Xero organisations when several are linked, and review the confirmation. AlgaPSA pauses sync and exports while it revokes access at Xero. Disconnect progress is saved and retried if cleanup fails; Retry Disconnect lets you try again. App credentials remain saved for a later connection.

If a permanent cleanup failure exposes Force Finalize, it removes credentials locally with an audited reason but does not confirm cleanup at Xero. Have the connection administrator verify the remaining access in Xero before treating that case as fully disconnected.

Operating checklist for accounting admins

Confirm the provider and organisation before changing mappings or executing an export.
Resolve connection and missing-scope messages first.
Check the most recent cycle, outstanding operations, drift, and exceptions during each billing run.
Reconcile payments, credit allocations, and reversals against linked invoices before month-end close.
Handle AlgaPSA-originated payments, credits, and voids separately in your accounting process.

Navigation

14.31. Connect Xero for Two-Way Invoice and Payment Sync