Xero API: Complete Developer Guide for Integration (2026)

Introduction

Whether you are building a SaaS product that syncs invoices, an internal tool that automates bank reconciliation, or a reporting dashboard that pulls real-time financial data, the Xero API gives you programmatic access to the full accounting ledger.

TL;DR — Quick Start in 5 Minutes

• Protocol: RESTful JSON over HTTPS
• Auth: OAuth 2.0 with PKCE (no more OAuth 1.0a)
• Base URL: https://api.xero.com/api.xro/2.0/
• Rate Limit: 60 calls/minute per tenant, 5,000/day
• SDKs: Official libraries for Python, Node.js, .NET, Java, Ruby, Go, PHP
• First API Call: Register an app at developer.xero.com, get your client ID, implement OAuth 2.0 flow, call GET /Invoices
• Need help? Our Xero integration team builds production-grade integrations

What is the Xero API? (Quick Overview)

Xero exposes six distinct APIs, each serving a different domain of accounting and business operations.

All follow the same RESTful conventions and share the same OAuth 2.0 authentication layer.

A single OAuth 2.0 connection can be authorized for multiple tenants. Use the GET /connections endpoint to list all authorized tenants and retrieve their IDs.

Request & Response Format: All endpoints accept and return JSON by default. Set Content-Type: application/json and Accept: application/json headers.

Some endpoints also support XML, but JSON is recommended for new integrations.

How Xero API Authentication Works (OAuth 2.0 Explained)

For server-side applications, use the standard Authorization Code flow.

For mobile or single-page apps, use the Authorization Code flow with PKCE (Proof Key for Code Exchange).

If you are building a native iOS app, see our detailed guide on Xero OAuth 2.0 integration with PKCE for iOS.

OAuth 2.0 Flow Steps

1. Register your app at developer.xero.com. Choose Web App or PKCE depending on your architecture.
2. Redirect the user to the Xero authorization URL with your client_id, redirect_uri, requested scope, and a state parameter for CSRF protection.
3. Exchange the authorization code for an access token and refresh token by calling the token endpoint.
4. Use the access token in the Authorization: Bearer {token} header for all API calls.
5. Refresh the token before it expires (tokens last 30 minutes). Use the refresh token to get a new access token without user interaction.

Scopes

Xero uses granular scopes to control API access. Request only the scopes you need:

Token Management Best Practices

• Store refresh tokens securely encrypted at rest, never in client-side code or version control.
• Proactively refresh tokens 2–3 minutes before the 30-minute expiry to avoid failed API calls.
• Handle token revocation gracefully if a user disconnects your app from Xero, your refresh token becomes invalid. Detect 401 responses and prompt re-authorization.
• Use the offline_access scope to receive a refresh token. Without it, you only get a short-lived access token.

Key Accounting API Endpoints

The Accounting API is the most-used Xero API. Here are the essential endpoints every integration needs to know:

Filtering and Querying

Most list endpoints support the where parameter for OData-style filtering. Examples:

GET /Invoices?where=Status=="AUTHORISED"&order=Date DESC
GET /Contacts?where=Name.Contains("Acme")
GET /BankTransactions?where=Date>=DateTime(2026,01,01)
GET /Invoices?where=Contact.ContactID==guid("abc-123-def")

Xero API Rate Limits (And How to Avoid 429 Errors)

Understanding these limits is critical for production integrations, especially high-volume sync operations.

For a deeper breakdown with practical examples, read our guide on Xero API sync limits and how many invoices you can sync per day.

Handling 429 (Too Many Requests) Errors

When you hit a rate limit, Xero returns a 429 status code with a Retry-After header indicating how many seconds to wait. Your integration should:

1. Implement exponential backoff: start with the Retry-After value, then double the wait time on subsequent 429s.
2. Use batching: POST and PUT endpoints accept arrays of up to 50 items per request, reducing the number of API calls.
3. Cache aggressively: store chart of accounts, tax rates, and other slowly-changing data locally.
4. Use If-Modified-Since:for sync operations, only fetch records that changed since your last sync.

Xero API Limitations (And Practical Workarounds)

No API is perfect. Xero has several well-documented limitations that developers encounter in production. We have published detailed guides on each:

• Journal API is read-only: The /Journals endpoint does not support POST or PUT. You can only read system journals.To create journal entries, use /ManualJournals instead. Filtering voided and reversal entries is also problematic see our full breakdown: Xero Journal API Limitations: How to Filter Voided and Reversal Entries.
• Trial Balance data gaps: The Trial Balance report via API may omit tracking category breakdowns and has limited date-range filtering compared to the Xero UI. Read our guide: Overcoming Xero API Limitations for Trial Balance Data Extraction.
• Aging reports are not available via API: There is no direct endpoint for AR/AP aging reports. You must reconstruct aging data from invoice due dates and payment records. We detail the workaround here: Xero API Aging Reports: AR/AP Data Extraction Limitations.
• Cash flow reports not directly available: The Xero API does not expose a cash flow statement endpoint. You need to derive it from bank transactions and journal data. Our guide explains how: How to Generate Cash Flow Reports from Xero When the API Does Not Offer It.
• Bank reconciliation API gap: The API capabilities for reconciliation differ between Xero and competitors like QuickBooks. See our comparison: Xero Has It. QuickBooks Does Not. The API Gap You Must Know.
• Foreign currency bank revaluation: Calculating accurate balances for foreign currency accounts requires a custom approach. Our detailed guide: Bank Revaluation in Xero: Calculating Accurate Balances for Foreign Currency Accounts Using API.

Webhooks

Xero webhooks notify your application in real-time when data changes in a connected organization, eliminating the need for constant polling.

Available Webhook Events

• Contacts: Create, Update
• Invoices: Create, Update
• Quotes: Create, Update
• Manual Journals: Create, Update
• Payments: Create, Update
• Credit Notes: Create, Update
• Purchase Orders: Create, Update

Webhook Security

Every webhook subscription includes a signing key. Xero signs each payload with an HMAC-SHA256 hash using this key. Your endpoint must:

1. Compute the HMAC-SHA256 of the raw request body using your signing key.
2. Compare the computed hash with the x-xero-signature header value.
3. Return 200 OK only if the signatures match. Return 401 otherwise.
4. Respond within 5 seconds or Xero will retry (up to 7 retries with exponential backoff).

Webhook Payload Format

          {
  "events": [
    {
      "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices/a1b2c3d4",
      "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "eventDateUtc": "2026-03-15T10:30:00.000Z",
      "eventType": "Update",
      "eventCategory": "INVOICE",
      "tenantId": "your-tenant-id",
      "tenantType": "ORGANISATION"
    }
  ],
  "firstEventSequence": 1,
  "lastEventSequence": 1,
  "entropy": "random-string"
}

SDKs & Libraries

Xero maintains official SDKs for all major languages. These handle OAuth 2.0 token management, request signing, serialization, and pagination automatically.

Sandbox & Testing

Best Practices for Testing

• Use the Demo Company for initial development and automated testing. It resets periodically, so do not rely on specific record IDs persisting.
• Create a dedicated trial organization for integration testing that requires persistent data. Xero offers a free 30-day trial for each new org.
• Implement idempotent operations — use Xero-provided IDs (GUIDs) for updates rather than creating duplicate records.
• Test rate-limit handling by intentionally exceeding limits in your test environment and verifying your backoff logic works correctly.
• Test token expiration by forcing a token refresh and verifying your app handles the flow without user intervention.
• Validate webhook signatures using the Intent to Receive validation step during webhook subscription setup.

Code Examples

Creating an Invoice (Python)

from xero_python.api_client import ApiClient
from xero_python.accounting import AccountingApi, Invoice, Contact, LineItem
from datetime import date

# Assumes you have a configured api_client with valid OAuth 2.0 tokens
accounting_api = AccountingApi(api_client)

contact = Contact(
    name="Acme Corporation",
    email_address="billing@acme.com"
)

line_item = LineItem(
    description="Web Development Services - March 2026",
    quantity=40.0,
    unit_amount=150.00,
    account_code="200",
    tax_type="OUTPUT"
)

invoice = Invoice(
    type="ACCREC",
    contact=contact,
    line_items=[line_item],
    date=date(2026, 3, 15),
    due_date=date(2026, 4, 14),
    reference="INV-2026-0315",
    status="DRAFT"
)

created_invoice = accounting_api.create_invoices(
    xero_tenant_id="your-tenant-id",
    invoices={"Invoices": [invoice]}
)

print(f"Invoice created: {created_invoice.invoices[0].invoice_id}")

Fetching Contacts with Pagination (Node.js)

const { XeroClient } = require("xero-node");

async function getAllContacts(xero, tenantId) {
  let allContacts = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await xero.accountingApi.getContacts(
      tenantId,
      null,  // ifModifiedSince
      null,  // where
      null,  // order
      null,  // iDs
      page,  // page number
      false  // includeArchived
    );

    const contacts = response.body.contacts;
    allContacts = allContacts.concat(contacts);

    // Xero returns 100 contacts per page
    hasMore = contacts.length === 100;
    page++;
  }

  console.log(`Fetched ${allContacts.length} contacts`);
  return allContacts;
}

OAuth 2.0 Token Refresh

import requests

def refresh_xero_token(client_id, client_secret, refresh_token):
    """Refresh an expired Xero OAuth 2.0 access token."""

    token_url = "https://identity.xero.com/connect/token"

    response = requests.post(
        token_url,
        data={
            "grant_type": "refresh_token",
            "refresh_token": refresh_token,
            "client_id": client_id,
            "client_secret": client_secret,
        },
        headers={"Content-Type": "application/x-www-form-urlencoded"}
    )

    if response.status_code == 200:
        tokens = response.json()
        # tokens["access_token"] - new access token (valid 30 min)
        # tokens["refresh_token"] - new refresh token (store this!)
        # tokens["expires_in"] - seconds until expiry (1800)
        return tokens
    else:
        raise Exception(f"Token refresh failed: {response.text}")

Frequently Asked Questions

Is the Xero API free?

Yes. Access to the Xero API itself is free. There are no per-call charges or separate API subscription fees. You only need a standard Xero subscription for each organization you connect to. Developer accounts and the Demo Company are also free. The cost is in your Xero subscription, not the API usage.

How do I get Xero API credentials?

Go to developer.xero.com and create a free developer account. Then create a new app from the “My Apps” dashboard. You will receive a Client ID and Client Secret. For PKCE-based apps (mobile, SPA), you only need the Client ID. Store your Client Secret securely and never expose it in client-side code.

What are Xero API rate limits?

Xero enforces three tiers of rate limiting: 60 calls per minute per tenant, 5,000 calls per day per tenant, and 10,000 calls per minute app-wide across all tenants. When you exceed a limit, the API returns a 429 Too Many Requests response with a Retry-After header. Use exponential backoff and batching to stay within limits.

Can I access bank feeds through the Xero API?

Yes, but only through the dedicated BankFeeds API, which is separate from the Accounting API. It allows you to push bank statement data into Xero for reconciliation. This API requires additional approval from Xero, and your app must meet their security requirements.

How do I handle Xero OAuth 2.0 token expiration?

Xero access tokens expire after 30 minutes. To maintain uninterrupted access, request the offline_access scope to receive a refresh token. Refresh tokens should be renewed proactively before expiry using the /connect/token endpoint. Always store the latest refresh token securely. If refresh fails, the user must re-authorize the app.

Can I create invoices and other transactions via the API?

Yes. The Accounting API supports full CRUD operations for invoices, bills, credit notes, payments, bank transactions, manual journals, contacts, and items. You can create records as DRAFT or AUTHORISED. Batch creation (up to 50 items per request) is also supported.

How do I integrate Xero with other accounting platforms?

You can either build separate integrations for each platform like QuickBooks or Sage, or use a unified integration layer that normalizes multiple accounting APIs. This approach simplifies multi-platform support and enables scalable automation.