How to Integrate with Xero API

The Xero API Integration Enforces Tight Rate Limits with a Strict Daily Cap

Xero applies some of the strictest rate limits among accounting APIs. Every connected organisation (tenant) has three separate limits that apply simultaneously.

Per-tenant limits:
 60 calls per minute
 5,000 calls per day (1,000 for starter tier apps)
 5 concurrent calls at one time

Per-app limit:
 10,000 calls per minute across all tenants

Response headers:
 X-MinLimit-Remaining
 X-DayLimit-Remaining
 X-AppMinLimit-Remaining

HTTP 429 → check Retry-After header for wait time

The daily limit of 5,000 calls per tenant is the most impactful constraint. For SaaS products that sync invoices, contacts, bank transactions, and journal entries, 5,000 calls can be exhausted during a single full data pull, especially since some endpoints require individual record fetches to get complete details. The concurrency limit of 5 simultaneous calls means you cannot parallelize requests aggressively to work around the per-minute cap.

Each API response includes headers showing remaining calls against each limit. When any limit is exceeded, Xero returns HTTP 429 with a Retry-After header. Your integration must track all three per-tenant limits and the global app limit simultaneously, and implement backoff logic that respects the Retry-After value for each.

Maesn Handles Xero Rate Limits Automatically: All Throttling Layers Are Tracked and Respected

Maesn tracks per-tenant and per-app rate limits internally. If a request is throttled, Maesn handles retry logic using the Retry-After header. The Maesn Dashboard provides real-time observability into API usage per connected Xero tenant.

The Xero API Integration Uses Inconsistent Pagination Across Endpoints

Xero does not apply pagination uniformly. Only a subset of endpoints supports paging: Invoices, Contacts, CreditNotes, BankTransactions, ManualJournals, Payments, PurchaseOrders, Prepayments, and Overpayments. Other endpoints return all records in a single response.

# Paginated endpoint (page-based)
GET /api.xro/2.0/Invoices?page=1&pageSize=100

Response includes:
 "pagination": {
   "page": 1,
   "pageSize": 100,
   "pageCount": 5,
   "itemCount": 487
 }

# Non-paginated endpoint (returns all records at once)
GET /api.xro/2.0/TaxRates
→ Returns full dataset, no pagination

For paginated endpoints, the default page size is 100 and the maximum is 1,000. The response includes a pagination object with page, pageSize, pageCount, and itemCount. This is well-structured, but the inconsistency across endpoints means your integration needs two different data retrieval strategies: page-based fetching for supported endpoints and full-response handling for everything else.

There is also a "where" parameter for filtering, but Xero recommends keeping these queries simple because complex filters can cause timeouts on larger organisations. The If-Modified-Since header helps with incremental syncs but does not capture all types of changes, especially partial updates to fields like DueDate or SentToContact.

Maesn Normalizes Xero Pagination: Consistent Page-Based Responses Across All Endpoints

Maesn applies consistent pagination across all Xero resources, regardless of whether the native endpoint supports paging. Your product receives the same response structure for every resource type across all 27+ accounting systems.

The Xero API Integration Requires OAuth 2.0 with a 25-Connection Limit Before Certification

Xero uses OAuth 2.0 with support for the authorization code flow, PKCE flow, and custom connections. Access tokens expire after 30 minutes. Refresh tokens must be used to obtain new access tokens, and offline_access scope is required to maintain connections longer than the initial session.

Authorization code flow:
 Access token:  30 minutes
 Refresh token: must be refreshed before expiry
 Scope:         openid profile email accounting.transactions ...

Connection limit (uncertified apps):
 25 Xero organisations maximum

Certification requirement:
 Beyond 25 connections → app must be certified by Xero
 Each organisation limited to 2 uncertified apps

The critical constraint for growing SaaS products is the 25-connection limit on uncertified apps. Until your app completes Xero's certification process, you cannot connect more than 25 organisations. Each Xero organisation is also limited to connecting a maximum of two uncertified apps. This means you may hit the connection ceiling during early customer onboarding.

The 30-minute access token window is also short. Long-running sync operations will need mid-process token refresh. If a refresh fails, the connection drops and the user must re-authorize.

Maesn Manages Xero Authentication Entirely: Token Refresh, Connection Limits, and Certification Are Handled Centrally

Maesn handles the full OAuth 2.0 lifecycle for Xero, including automatic token refresh before expiration and secure token storage. Maesn's existing Xero certification removes the 25-connection limit for your integration.

The Xero API Integration Webhooks Cover Only Four Event Categories

Xero supports webhooks, but only for a limited set of events: contacts (create/update), invoices (create/update), credit notes (create/update), and subscriptions (create/update). There is no webhook support for bank transactions, payments, journal entries, accounts, or tax rates.

Supported webhook events:
 Contact   → CREATE, UPDATE
 Invoice   → CREATE, UPDATE
 CreditNote → CREATE, UPDATE
 Subscription → CREATE, UPDATE

Validation: HMACSHA256 with webhook signing key
Endpoint must: respond within 5 seconds, HTTPS on port 443
Retry policy: immediate retry, then every 15 minutes for 24 hours
After 24 hours without success → webhook disabled

For the four supported categories, webhooks work well. Xero validates intent to receive using HMACSHA256 signature verification. Your endpoint must respond within 5 seconds on HTTPS port 443. If delivery fails, Xero retries with decreasing frequency for 24 hours. After that, the webhook is disabled and must be manually re-enabled. Events that occur while the webhook is in retry or disabled status are saved for up to 31 days and replayed once the subscription is healthy again.

For everything not covered by webhooks, your integration falls back to polling with the If-Modified-Since header or periodic full syncs. This creates a split architecture where some resources are event-driven and others are poll-based.

Maesn Handles Xero Event Processing: Webhook and Polling Sync Run Through a Single Interface

Maesn processes both webhook events and poll-based sync for Xero through a single unified interface. Your integration receives consistent event notifications regardless of whether the data came from a webhook or a scheduled sync.

Xero Partner Program and Marketplace Listing

Xero offers a structured partner program through the Xero Developer Portal. A free developer sandbox is available. Production access requires registering and creating your app. The program is free to start, with a 15% revenue share on App Store sales. Certification is required beyond 25 connections.

For marketplace visibility, at least Plus partner status is required to list in the Xero App Store. The App Store drives qualified inbound from the UK, Australia, NZ, and US markets.

Maesn Supports the Xero Partner Listing Process

Unlike most unified API providers, Maesn does not put its name on your marketplace listing. Your app appears under your own brand in the Xero App Store. For a full breakdown of partnership requirements, read the Maesn accounting integration partnerships guide.

Why Teams Use Maesn for Their Xero API Integration

Integrating directly with the Xero API means working within a 5,000 calls per day limit, handling inconsistent pagination across endpoints, managing OAuth 2.0 with a 25-connection ceiling before certification, and building a split sync architecture for webhook-covered and non-webhook resources. Together, these create a maintenance surface that grows with every connected customer.

Maesn abstracts all of it behind a unified API. One integration gives you rate limit management, consistent pagination, managed authentication without connection limits, unified event processing, and access to 27+ additional accounting systems including DATEV, Moneybird, QuickBooks, sevdesk, and more.

‍

Check the Maesn documentation for Xero or talk to the Maesn team to get started