Support  ›  Getting started  ›  Connecting Xero

Connecting Xero

TrueBooks posts each settlement as a single, fully-broken-out invoice in Xero. To do that, it needs OAuth access to one Xero organisation and a synced copy of your chart of accounts.

What we'll ask Xero for

When you click Connect Xero, you're sent to Xero's standard OAuth screen. The scopes we request are:

• Read & write invoices — to create the settlement invoices, void/repost them when needed, and look them up.
• Read accounts — so the mapping screen can show your real account codes rather than us guessing.
• Read tax types — so the right rate is applied at the line level when we post.
• Read connections — Xero's standard tenant-discovery scope; without it we can't ask which organisation you authorised.

We don't ask for bank-feed write access, payroll, employees, or anything else. If a permission isn't listed above, we don't have it.

The connection flow

1. In TrueBooks, open Settings → Account and click Connect Xero.
2. Sign in to Xero (or carry on if you're already signed in).
3. Xero shows the consent screen. If you have access to more than one organisation, pick the one TrueBooks should post into.
4. Click Allow access. Xero redirects you back to TrueBooks.
5. You'll see a confirmation banner — "Xero connected successfully". The connection card now shows the tenant name and when it was linked.

Syncing the chart of accounts

Right after the connection lands, TrueBooks pulls your chart of accounts and tax types into the mapping screen. From Accounts & Taxes you'll see every account code and tax rate Xero knows about, ready to be linked to a transaction category.

If you add a new Xero account later (e.g. you create a dedicated Amazon Sales ledger), open Accounts & Taxes and click Sync from Xero to pick it up. The sync is idempotent — running it never overwrites your existing mappings.

Reconnecting and disconnecting

Xero's access tokens are short-lived and refresh automatically every 30 minutes. If something invalidates the refresh token — your Xero password rotated, the user who connected lost access, etc. — TrueBooks marks the connection as Reconnect required and stops posting. Reconnecting re-authorises the same tenant; nothing in your Xero org is affected and existing posted invoices remain in place.

Disconnecting tells Xero to revoke our token, then clears the credentials from our side. Posted invoices stay in Xero; we just stop being able to post new ones or run integrity checks.

Common gotchas

• "No Xero organisation found" — you signed in as a Xero user who doesn't have access to any organisation. Sign in as the user you actually use to post invoices, or have your Xero admin grant you access first.
• "Authorisation cancelled" — you closed the consent window or clicked back. Just retry; nothing is left in a half-open state.
• Wrong tenant connected — disconnect the current connection in Settings → Account, click Connect Xero again, and pick the right organisation in Xero's tenant list.

Next up

With Amazon and Xero both connected, the only step before your first post is mapping your transaction categories to the right account codes and tax rates: Account & tax mappings.