What we do
Tools
Industries
Department
How we workLet's talk →
Home/Xero/Xero API for Developers
Xero developer notes

Writing Code Against the Xero API: Grants, Tenants, Scopes and the Call Budget

The Xero API is REST with OAuth 2.0, and the accounting endpoints cover invoices, bills, contacts, payments, bank transactions, manual journals and reports. This page is for the person writing the integration. Still choosing between an App Store app and a custom build? Start on the Xero page.

What a working call needs

An access token from the OAuth 2.0 flow. It lasts 30 minutes. Request the offline_access scope to get a refresh token, which expires after 60 days without use.

A tenant ID. After the user authorizes, call GET https://api.xero.com/connections to list the organizations they connected, and send the right one in the xero-tenant-id header on every request.

The right scopes. Apps created since 2 March 2026 ask for granular scopes such as accounting.invoices or accounting.payments.read, not the older broad ones.

Which way your app authenticates

You choose this when you create the app in the Xero developer portal, and it's hard to change later.

You are building Use Know this
A server-side app that many organizations will connect Standard authorization code flow (web app) A user signs in to Xero, picks the organizations and approves your scopes. You store and refresh tokens per connection and send the tenant ID with each call.
A desktop or mobile app, or anything that can't keep a secret Authorization code with PKCE Same user approval, without a client secret in the app. Token handling and tenant IDs work the same way.
A back-office job for one organization with no user present A Custom Connection Client credentials for one organization in Australia, New Zealand, the UK or the US, no refresh token or tenant header. Xero stops new Custom Connection apps and subscriptions on 1 December 2026; existing ones keep running, so a new build should be a standard OAuth 2.0 app.
That same one-organization job, outside those regions or without the subscription A web or PKCE app authorized once by an admin Someone approves it once, then your service refreshes the token on a schedule. Alert when a refresh fails, because nobody will be around to notice.

How far one organization's daily calls go

Limits apply per connected organization: 5 calls at once, 60 a minute, and 5,000 a day on paid developer tiers (1,000 on the free Starter tier). Across all organizations, an app gets 10,000 calls a minute.

Example: an hourly sync for one busy organization on a paid tier
Daily allowance 5,000
Hourly pull of changed invoices, 4 pages (Using the If-Modified-Since header, 24 runs) −96
Hourly pull of changed contacts (2 pages, 24 runs) −48
600 payments posted one call at a time (Batching would cut this sharply) −600
Nightly reports for a dashboard −20
A careless full re-read of every invoice (The usual reason syncs hit the cap) −3,000
Left for retries and everything else 1,236

Go over a limit and Xero answers 429 with a Retry-After header. Wait that long rather than retrying straight away. Webhooks remove most polling, and pulling only records modified since your last run is what keeps a sync well inside the cap.

Taking webhooks from Xero

Xero sends webhooks for invoices and contacts, and now credit notes. A webhook tells you something changed; you fetch the record yourself.

  1. 1

    Add a webhook to your app

    In the developer portal, open your app's webhooks settings, give your endpoint URL and choose the event categories. Xero issues a webhook key for checking signatures.

  2. 2

    Pass the intent-to-receive check

    Before it goes live, Xero sends test requests, some correctly signed and some not. Your endpoint must accept the good ones and reject the bad ones, or the subscription won't activate.

  3. 3

    Verify every payload

    Compute an HMAC-SHA256 of the raw request body with your webhook key, Base64 it, and compare it with the x-xero-signature header. Answer 401 if it doesn't match.

    Watch for: your framework parsing the JSON before you hash it. Hash the raw bytes exactly as they arrived.

  4. 4

    Queue, then fetch

    Each event carries the tenant, the category and the resource ID. Acknowledge quickly, put the work on a queue, and fetch the full invoice or contact through the API.

Why Xero integrations stop working weeks after launch

The refresh token is thrown away

How you'll know: Calls start failing with invalid_grant and the user has to connect again.

Fix: Each refresh hands back a new refresh token. Save it every time, in the same transaction as the access token, and refresh well before 60 days pass even for quiet organizations.

Writing to the wrong organization

How you'll know: Invoices appear in a client's demo company, or in another client's file.

Fix: One user can connect several organizations. Store the tenant ID from /connections with each customer record, and never default to the first one in the list.

Broad scopes on a new app

How you'll know: A new app gets 401 with insufficient_scope on endpoints that worked in older code samples.

Fix: Request the granular scope for each endpoint you call, such as accounting.banktransactions for bank transactions. Existing users have to reconnect to pick up new scopes.

Counting on the Journals endpoint

How you'll know: Your design reads /Journals for a full ledger, and the call is refused.

Fix: Journals now needs the Advanced developer tier and Xero's security assessment. Manual journals stay available on every tier. Plan the reporting around what your tier can reach.

Sizing the developer tier too late

How you'll know: A sixth client file won't connect.

Fix: Starter allows 5 connections, Core 50, Plus 1,000 and Advanced 10,000, each with a monthly fee in AUD and a data allowance. If you serve many client files, budget for the tier before you build.

Questions people ask

Is the Xero API free to use?

Partly. Since 2 March 2026 developer access is tiered by connections. The Starter tier is free, with up to 5 connections and 1,000 calls a day per organization. Core, Plus and Advanced have monthly fees, and Enterprise is priced on application. Each connected organization still needs its own Xero subscription.

Do I need a developer to use the Xero API?

To build a connection, yes. A test call in the API Explorer takes minutes. A connection that refreshes tokens, keeps tenants apart, respects the call limits and recovers from a failed run is development work, and it needs someone to look after it when Xero changes scopes or terms.

Does the Xero API support webhooks?

Yes, for invoices, contacts and credit notes. Each webhook is signed with your app's webhook key and tells you which record changed, so you fetch the details through the API. Your endpoint has to pass Xero's intent-to-receive check first.

What authentication does the Xero API use?

OAuth 2.0. Most apps use the authorization code flow, as a web app or with PKCE, and the user approves the scopes the app requests. Custom Connections use client credentials for a single organization, but Xero stops new ones on 1 December 2026.

Is there a free, open-source way to connect to Xero?

Yes. Xero publishes open-source SDKs for Node, Python, Ruby, PHP, .NET and Java, which handle the OAuth exchange and request models. You still write the integration logic: what to sync, how to match records, and what to do when a call fails.

Who builds and maintains a Xero API integration?

That's work n-frames takes on. We write the connection from your other systems into Xero on the right grant type and scopes, keep tokens and tenants straight, and keep it running through Xero's tier and scope changes.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.