Xero API Integration: A Complete Guide for UK Businesses

The Xero API gives developers programmatic access to Xero’s full accounting platform — creating invoices, syncing contacts, reconciling payments, managing bank transactions and pulling financial data into your own platform. For businesses that use Xero and have a separate system that touches money — an ecommerce platform, a CRM, a job management system, a subscription billing tool — a custom Xero integration eliminates the manual work of keeping both systems in sync. This guide covers how the Xero API works, what it can automate, and what a properly built integration looks like.

What the Xero API can access

The Xero API is comprehensive — it covers virtually everything you can do in Xero manually. The most commonly integrated endpoints are:

Invoices and credit notes — create, update and retrieve invoices and credit notes. Line items, tax rates, due dates, reference numbers, tracking categories and project codes are all configurable. Invoices can be created in Draft, Submitted or Authorised status depending on your approval workflow. This is the most common integration endpoint — every order, subscription payment or service completion becoming a Xero invoice automatically.

Contacts — create and update customer and supplier records. Contact details, addresses, payment terms, default accounts and currency settings. Keeping Xero contacts in sync with your CRM or customer database means no duplicate data entry and consistent naming across systems.

Payments — apply payments to invoices, allocate credit notes and mark invoices as paid. Combined with a payment processor like Stripe or GoCardless, this enables automatic reconciliation — payment confirmed by Stripe, payment applied to the Xero invoice, invoice marked paid, all without manual intervention.

Bank transactions — create manual bank transactions, retrieve bank statement data and interact with Xero’s bank reconciliation workflow. Useful for platforms that need to push non-payment-processor transactions into Xero.

Accounts and tax rates — retrieve the chart of accounts and tax rates configured in a Xero organisation. Essential for mapping your platform’s products and services to the correct Xero accounts and tax codes — VAT at 20%, zero rated, exempt, reverse charge — without hardcoding values that differ between organisations.

Reports — retrieve balance sheet, profit and loss, trial balance and cash summary reports from Xero. Useful for platforms that need to display financial summaries to clients or users without requiring them to log into Xero directly.

Tracking categories — Xero’s cost centre and department tracking system. If your organisation uses tracking categories for departmental reporting, the integration can apply the correct categories to each invoice line automatically based on data from your platform.

How Xero API authentication works

The Xero API uses OAuth 2.0. Unlike simple API key authentication, OAuth requires a user to actively authorise your application to access their Xero organisation. The flow is: your application redirects the user to Xero’s authorisation page, the user logs in and grants access, Xero redirects back to your application with an authorisation code, your application exchanges the code for access and refresh tokens.

Access tokens are valid for 30 minutes. When an access token expires, the integration uses the refresh token to obtain a new one automatically — this is called token refresh and happens transparently without the user having to re-authorise. Refresh tokens are valid for 60 days but are refreshed each time they’re used, effectively keeping the connection live indefinitely as long as the integration runs regularly.

Both access and refresh tokens must be stored securely. They are credentials that give access to a Xero organisation’s financial data — encrypting them in the database and never exposing them in logs or client-side code is non-negotiable.

For multi-organisation setups — accountancy platforms connecting to multiple clients’ Xero organisations, or businesses managing multiple entities — each organisation has its own set of tokens. The integration maintains separate token sets per organisation and applies the correct one to each API call.

Xero’s API rate limits

Xero applies rate limits at the app and per-organisation level. The key limits are: 60 API calls per minute per organisation, and a concurrent connection limit. For integrations that process high volumes of invoices — syncing thousands of orders from an ecommerce platform, for example — the rate limits need to be managed carefully. A properly built integration queues API calls, respects rate limit responses (HTTP 429), implements exponential backoff on retries and spreads bulk operations across time rather than firing all requests simultaneously.

Xero also has a daily limit on the number of API calls per organisation. For most business integrations this isn’t a practical constraint, but for platforms serving large volumes of transactions it’s worth modelling expected call volumes during scoping.

Xero sandbox and testing

Xero provides a demo company in every Xero account for development and testing purposes. The demo company is accessible through the standard OAuth flow and responds to all API calls exactly as a live organisation would. All integration development should be done against the demo company before connecting to a live Xero organisation.

Testing should cover the full range of scenarios: successful invoice creation with each tax rate used, contact creation and update, payment application and reconciliation, edge cases like duplicate prevention, rate limit handling and token refresh behaviour. A thorough test suite in sandbox means the go-live is low-risk.

What a properly built Xero integration looks like

A well-built Xero integration has several characteristics that distinguish it from a quick implementation. Token storage is encrypted. Token refresh is automatic and logged. API calls are queued and rate-limit-aware. Every API call result is logged with enough context to diagnose issues later. Failed syncs trigger alerts and queue the record for retry rather than silently failing. Idempotency is handled — if an order sync runs twice (due to a retry), it doesn’t create duplicate invoices in Xero.

The invoice data mapping is also critical. Getting tax rates wrong on invoices has real accounting consequences. The mapping between your platform’s products, tax treatments and Xero’s accounts and tax codes is defined and tested carefully during the build, not hardcoded and hoped for the best.

For the full service details and pricing, see the Xero API integration service. For how Xero connects with Stripe payments, see Xero and Stripe integration. For WooCommerce specifically, see Xero WooCommerce integration. For what the build costs, see the Xero API integration cost guide.

Related posts

• How to automate invoices with the Xero API
• Xero and Stripe integration: automating payment reconciliation
• Xero WooCommerce integration: how it works
• Xero API integration cost

Common integration mistakes to avoid

Hardcoding account codes. Xero account codes differ between organisations. An integration that hardcodes “200” as the sales account works for one Xero setup and breaks for another. A properly built integration retrieves the chart of accounts from the connected organisation and maps to named accounts or configurable settings rather than hardcoded codes.

Ignoring token expiry. The most common cause of Xero integration failures in production is expired refresh tokens. If the integration doesn’t run for 60 days, the refresh token expires and the connection breaks silently. A well-built integration monitors token health, alerts before expiry and has a re-authorisation flow that doesn’t require developer intervention.

Creating contacts without deduplication. Running an invoice sync without checking whether the contact already exists in Xero creates duplicate contact records. The integration should check for an existing contact by email or name before creating a new one, and update rather than duplicate where the contact already exists.

Not handling Xero validation errors. Xero returns detailed validation errors when an invoice can’t be created — invalid account code, missing required field, duplicate invoice number. These need to be caught and handled explicitly, not silently swallowed. A failed invoice creation should be logged with the full error, the problematic record flagged for review, and an alert sent so the issue is addressed before it builds up.

Syncing everything immediately. For platforms with high transaction volumes, syncing every event to Xero in real time can exhaust rate limits quickly. A batch sync approach — queuing events and processing them in controlled batches — is more resilient than real-time sync for high-volume use cases.

Multi-currency Xero integrations

If your platform sells in multiple currencies, the Xero integration needs to handle currency correctly. Xero supports multi-currency on paid plans. Invoices created in a currency other than the organisation’s base currency need the currency code specified. Exchange rates can either be set explicitly on the invoice or left to Xero to apply its daily rate.

For businesses where exchange rate accuracy on invoices matters — for VAT purposes or for accurate revenue reporting — setting the exchange rate explicitly at the time the invoice is created is the more reliable approach. The integration can retrieve a rate from your payment processor (Stripe, for example, records the exchange rate on each payment) and pass it to Xero.

If you need help with a custom API integration for your website or business application, I can help. I build bespoke API integrations for UK businesses. See API integration pricing or get in touch to discuss your project.