Xero API Integration: What to Plan Before You Build

A Xero API integration is quick to start and slow to finish. You can connect an organisation and read invoices in an afternoon. What takes the time is everything a production integration needs: tokens that expire, customers with several organisations, rate limits, webhooks that don’t cover everything, keeping data in sync, and mapping Xero’s model onto yours. Plan those up front and the build goes smoothly; discover them in production and they become support tickets.

The plan at a glance

Area	The decision
Authentication	How you store tokens, refresh them, and handle revoked connections
Organisations	How one user with several Xero organisations maps to your accounts
Rate limits	How you queue and pace calls so one big customer doesn’t starve the rest
Change detection	Which changes come by webhook, and what you poll or reconcile
Sync	Full load first, then incremental, and how you recover from gaps
Data mapping	How Xero’s invoices, contacts, tax and currencies map to your model
Marketplace	Whether you’ll list in the Xero App Store, and what that requires

Authentication and connections

Xero uses OAuth 2.0. Access tokens are short-lived and refresh tokens rotate, so every refresh must store the new refresh token straight away. If two processes refresh at once and one saves an older token, the connection breaks. Treat these as normal states with their own handling:

• token refreshed: store it atomically, before anything else happens
• connection revoked by the customer: stop syncing, show it clearly, offer a reconnect
• refresh failed: retry carefully, then flag it for the customer rather than failing silently

Organisations

One Xero user can authorise several organisations (tenants) in a single connection. Decide how that maps to your product: one account per organisation, or several organisations under one customer. Get this wrong and data from two businesses ends up in the same place.

Rate limits

Xero limits calls per organisation over short and long windows, and per app. Check the current limits in Xero’s developer documentation rather than relying on numbers from an old blog post, since they change. Design for them anyway:

• queue calls per organisation, so a large customer’s initial load doesn’t block everyone else
• honour retry headers and back off
• prefer incremental requests over re-reading everything

Webhooks and change detection

Xero’s webhooks cover some entities, such as contacts and invoices, but not everything you may need. Webhooks are signed, and your endpoint must verify the signature. Use them to trigger a sync, not as the only source of truth: a missed webhook should be caught by a scheduled reconciliation, not discovered by a customer.

Sync strategy

1. Initial load. Page through history, within rate limits, and expect it to take a while for large organisations.
2. Incremental sync. Ask only for records modified since the last successful sync.
3. Reconciliation. Periodically compare totals or recent records to catch anything missed.
4. Recovery. If a sync fails halfway, resume from the last checkpoint instead of starting over.

Data mapping

Most of the long-term work sits here. Decide how you handle:

• invoice statuses, credit notes, and part payments
• contacts that are both customers and suppliers
• multi-currency amounts and the exchange rate used
• tax, which varies by country and organisation settings
• deleted or voided records, which still matter for history

Test against real data from several organisations, not just the demo company.

Listing in the Xero App Store

If you want to appear in Xero’s marketplace, the app goes through Xero’s certification and has to meet their requirements for connection flows, branding and data handling. Decide early, because some of those requirements are easier to design in than to retrofit.

Direct, or through a unified API?

If you also need QuickBooks or other platforms, a unified accounting API may be faster to start. The trade-offs are in Codat vs direct accounting APIs, and the general integration questions are in the API integration checklist.

I’ve built Xero integrations for a lending platform, including a buy now, pay later service offered through the Xero marketplace. If you’re planning one, see accounting and fintech integrations, or start with a migration and integration assessment.