Connect Xero

Cash Runway builds its forecast from your Xero data — reconciled bank transactions, unpaid invoices (AR), unpaid bills (AP), and any recurring templates. This page walks through the one-time OAuth connection and what happens during the first sync.

Prerequisites

Before you start:

• You need an active Xero organisation.
• You must have the Xero "Adviser" or "Standard" role on that organisation. (If the "Connect Xero" button takes you back without progress, the most common cause is trying to connect as a Read-only user.)
• You should be logged into the same Xero account in your browser — it saves a login round-trip on the consent screen.

Step 1 — Click "Connect Xero"

Inside the Cash Runway dashboard, you'll see a Connect Xero card on the home screen when no connection exists yet.

Click it. You are redirected to Xero's OAuth consent page.

Step 2 — Consent in Xero

Xero shows you exactly which organisation and which scopes Cash Runway is asking for:

• Accounting — read (transactions, invoices, bills, contacts)
• Accounting — settings read (chart of accounts, tax rates)
• Offline access (so we can refresh the token without asking you to reconnect)

If you manage more than one Xero org, pick the right one from the dropdown before clicking Allow access.

One org, one Cash Runway company

Cash Runway locks the first Xero tenant you connect to the Cash Runway company you're in, so the two cannot accidentally diverge later. If you want to track a second Xero organisation, create a second Cash Runway company from the org switcher first, then connect Xero from there.

Step 3 — Initial sync runs

After you consent, Xero sends you back to Cash Runway and the initial sync kicks off automatically in the background.

The sync pulls:

• 90 days of reconciled bank transactions
• All unpaid invoices (AR) and their aging
• All unpaid bills (AP)
• Any recurring invoice and bill templates

Typical timings:

Org size	First-sync time
< 500 transactions	30–90 seconds
500–5,000 transactions	1–3 minutes
5,000+ transactions	3–8 minutes

A progress indicator at the top of the dashboard shows live status. You can keep browsing — the dashboard will fill in as the worker completes each stage.

What Cash Runway does not touch

We never write to Xero. No invoices, bills, or payments are created or modified. The connection is read-only, using the standard accounting.transactions.read and accounting.reports.read scopes.

Troubleshooting

• "Connect Xero" loops back without connecting → you are signed into a Xero account that does not have admin access on any org.
• "Tenant already connected elsewhere" → this Xero org is already bound to a different Cash Runway company. Switch to that company, or archive it first if you want to re-bind.
• Sync sits at 0% for more than a minute → check Settings → Integrations → Xero for a red "Re-authorise" banner.

When something goes wrong

Three banners surface Xero-side issues, and they mean different things — most importantly, only one of them wants you to click Reconnect:

"Xero data limit reached" (blue, no button)

Your Xero organisation has hit Xero's API rate limit (5,000 calls per day, or 60 calls per minute). Syncing is paused and will resume automatically once the limit resets — there is nothing for you to do. Do not click Reconnect; reconnecting makes it worse, because it resets the sync cursor and triggers a full backfill that consumes even more of the same daily quota. This banner is blue and carries no button precisely because it is not actionable.

"Xero is having service issues" (amber, status link)

Xero's own API is returning errors right now. Your connection is fine — there is nothing for you to do. We keep retrying automatically and your dashboard may show data up to ~12 hours stale until they recover. The banner links to status.developer.xero.com so you can confirm from Xero's status page that the issue is theirs, not yours.

"Xero re-authorisation required" (amber, Reconnect button)

Your OAuth grant has expired (Xero refresh tokens last 60 days) or was revoked upstream. Syncing is paused entirely until you click Reconnect and step through the consent screen again. Nothing else fixes this — it requires operator action. This is the only banner where reconnecting is the right move; the blue "data limit reached" banner above means your token is fine and reconnecting would only burn more quota.

If a row in Settings → Connections → Xero shows a "Degraded" pill but no banner appears at the top of the page, the connection has recovered since the last failed run and we are back to normal — the row badge just remembers the most recent state until the next successful sync overwrites it.

"Last incremental sync: X days ago" reads amber or red

Each connection row shows two timestamps under the Sync now button:

• Last sync advances on every "Sync now" click. This is how recently Cash Runway TRIED to talk to Xero.
• Last incremental sync advances when the sync actually fetched fresh records from Xero's incremental endpoints. This is how recently we made forward progress.

The two diverge when the sync runs but doesn't make progress — a possibility when the incremental cursor is far behind Xero's real-time edge and the per-source page budget caps out before reaching the most recent records.

• Amber (> 7 days) — the cursor is drifting. No action needed yet, but worth checking on the next "Sync now" tick.
• Red (> 30 days, or "never") — the cursor isn't advancing. Click Sync now on the same row. Every Sync now click runs the full incremental pipeline (syncPayments + the invoice-flush helper) regardless of how the underlying chunked backfill divided the work, so a single click recovers the cursor in the common case. If the line stays red after a sync, contact support.

The cursor age clamp caps each tick's catch-up window at 30 days, so a stuck cursor self-heals over time even without intervention.

Next step

Once the initial sync finishes, you are ready to read your first forecast.