Xero
This page contains the setup guide and reference information for the Xero source connector.
Prerequisites
- Tenant ID - The ID of your Xero organization (required)
- Start Date - The date from which you want to start replicating data (UTC format)
For multi-tenant Xero accounts, you'll need to select which organization to connect with using the Tenant ID. You can find your Tenant IDs by following the 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
There are two currently supported ways to authenticate with Xero:
For the bearer token strategy, please follow instructions to obtain all requirements:
- Client ID
For the OAuth client credentials, please follow instructions to obtain all requirements:
- Client ID
- Client Secret
Setup guide
- Create an application in Xero development center.
- Select the appropriate authentication method (bearer token or OAuth client credentials).
- Configure the required scopes mentioned in the Prerequisites section.
- For bearer token authentication:
- Follow the PKCE flow to obtain an access token.
- You can use Postman as described in the migration guide.
- For OAuth client credentials:
- Ensure you have both 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:ssZ
from which you'd like to replicate data.
Supported sync modes
The Xero source connector supports the following 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
Dates transformation
As Xero uses .NET, some date fields in records could be in .NET JSON date format which look like /Date(1419937200000+0000)/
. The connector automatically detects and transforms these dates into ISO 8601 format for consistency and easier data processing.
The connector also handles ISO 8601 formatted dates and ensures all datetime fields use a consistent format with UTC timezone.
Incremental Sync
This connector supports incremental sync for all streams. The connector uses the UpdatedDateUTC
field as the cursor field to track which records to sync incrementally. During the first sync, the connector will fetch all data from the start date you specify. In subsequent syncs, it will only fetch records that have been updated since the last sync.
Error Handling
The connector implements automatic handling for common API errors:
- 401 Unauthorized: The connector will attempt to refresh the access token and retry the request.
- 403 Forbidden: The connector will log the error and skip the affected record.
- 429 Rate Limit Exceeded: The connector will respect the Retry-After header and automatically retry after waiting the specified time.
Performance considerations
The connector is restricted by Xero API rate limits:
- 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 with a Retry-After header indicating how many seconds to wait before retrying.
Pagination
The connector automatically handles pagination for all streams, using a page size of 100 records per request.
Migration Guide
If you are upgrading from a previous version of the connector, please refer to the migration guide for important information about changes between versions.
Reference
Config fields reference
Changelog
Expand to review
Version | Date | Pull Request | Subject |
---|---|---|---|
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] |