Xero
Use this page to set up the Xero source connector and find reference information.
Prerequisites
- Tenant ID - Your Xero organisation ID (required)
- Start Date - The date to start replicating data from (UTC format)
For multi-tenant Xero accounts, use the Tenant ID to select the organisation you want to connect. Find your Tenant IDs by following Xero documentation.
Required list of scopes to sync all streams:
- accounting.attachments.read
- accounting.budgets.read
- accounting.contacts.read
- accounting.journals.read
- accounting.reports.read
- accounting.reports.tenninetynine.read
- accounting.settings.read
- accounting.transactions.read
- assets.read
- offline_access
Authentication
You can authenticate with Xero in two supported ways:
For bearer token authentication, follow instructions to obtain:
- Client ID
For OAuth client credentials, follow instructions to obtain:
- Client ID
- Client Secret
Setup guide
- Create an application in Xero development center.
- Select your authentication method: bearer token or OAuth client credentials.
- Configure the required scopes listed in the Prerequisites section.
- For bearer token authentication:
- Follow PKCE flow to obtain an access token.
- You can use Postman as described in migration guide.
- For OAuth client credentials:
- Make sure you have the Client ID and Client Secret from your Xero application.
- Enter your Xero Organisation’s Tenant ID.
- Enter a Start Date in UTC format
YYYY-MM-DDTHH:mm:ssZfor when you want data replication to begin.
Supported sync modes
The Xero source connector supports these sync modes:
Supported streams
- Accounts
- BankTransactions
- BankTransfers
- BrandingThemes
- ContactGroups
- Contacts
- CreditNotes
- Currencies
- Employees
- Invoices
- Items
- ManualJournals
- Organisation
- Overpayments
- Payments
- Prepayments
- PurchaseOrders
- RepeatingInvoices
- TaxRates
- TrackingCategories
- Users
Date transformation
Xero uses .NET, so some record date fields may use .NET JSON date format and look like /Date(1419937200000+0000)/. The connector automatically detects and transforms these dates into ISO 8601 format. This provides consistency and makes data processing easier.
The connector also handles ISO 8601 formatted dates. It gives all datetime fields a consistent format with the UTC timezone.
Incremental sync
You can use incremental sync for every stream. The connector uses the UpdatedDateUTC field as the cursor field to track records. Your first sync fetches all data from your specified start date. Later syncs only fetch records updated since the previous sync.
Error handling
The connector automatically handles common API errors:
- 401 Unauthorized: The connector attempts to refresh the access token and retry the request.
- 403 Forbidden: The connector logs the error and skips the affected record.
- 429 Rate Limit Exceeded: The connector follows the Retry-After header and automatically retries after the specified wait time.
Performance considerations
The following Xero API rate limits restrict the connector:
- Concurrent Limit: 5 calls in progress at one time
- Minute Limit: 60 calls per minute per tenant
- Daily Limit: 5000 calls per day per tenant
- App Minute Limit: 10,000 calls per minute across all tenants
When rate limits are exceeded, the API returns a 429 HTTP status code. The Retry-After header states how many seconds to wait before retrying.
Pagination
The connector automatically handles pagination for every stream. It uses a page size of 100 records per request.
Migration guide
If you’re upgrading from an earlier connector version, see migration guide for important information about changes between versions.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 2.1.6 | 2026-06-30 | 79089 | Update dependencies |
| 2.1.5 | 2026-02-25 | 71340 | Resolve the generator returned from JsonDecoder into dictionary |
| 2.1.4 | 2025-03-01 | 55142 | Update dependencies |
| 2.1.3 | 2025-02-22 | 54526 | Update dependencies |
| 2.1.2 | 2025-02-15 | 54042 | Update dependencies |
| 2.1.1 | 2025-02-08 | 43841 | Update dependencies |
| 2.1.0 | 2024-10-23 | 47264 | Migrate to Manifest-only |
| 2.0.1 | 2025-01-10 | 51034 | Fix for time part being removed from all datetimes fields |
| 2.0.0 | 2024-06-06 | 39316 | Add OAuth and Bearer strategies |
| 1.0.1 | 2024-06-06 | 39264 | [autopull] Upgrade base image to v1.2.2 |
| 1.0.0 | 2024-04-30 | 36878 | Migrate to low code |
| 0.2.6 | 2024-05-17 | 38330 | Updating python dependencies |
| 0.2.5 | 2024-01-11 | 34154 | prepare for airbyte-lib |
| 0.2.4 | 2023-11-24 | 32837 | Handle 403 error |
| 0.2.3 | 2023-06-19 | 27471 | Update CDK to 0.40 |
| 0.2.2 | 2023-06-06 | 27007 | Update CDK |
| 0.2.1 | 2023-03-20 | 24217 | Certify to Beta |
| 0.2.0 | 2023-03-14 | 24005 | Enable in Cloud |
| 0.1.0 | 2021-11-11 | 18666 | 🎉 New Source - Xero [python cdk] |