Skip to main content

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

  1. Create an application in Xero development center.
  2. Select the appropriate authentication method (bearer token or OAuth client credentials).
  3. Configure the required scopes mentioned in the Prerequisites section.
  4. For bearer token authentication:
  5. For OAuth client credentials:
    • Ensure you have both Client ID and Client Secret from your Xero application.
  6. Enter your Xero Organisation's Tenant ID.
  7. 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

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

Field
Type
Property name
string
tenant_id
string
start_date
object
credentials

Changelog

Expand to review
VersionDatePull RequestSubject
2.1.42025-03-0155142Update dependencies
2.1.32025-02-2254526Update dependencies
2.1.22025-02-1554042Update dependencies
2.1.12025-02-0843841Update dependencies
2.1.02024-10-2347264Migrate to Manifest-only
2.0.12025-01-1051034Fix for time part being removed from all datetimes fields
2.0.02024-06-0639316Add OAuth and Bearer strategies
1.0.12024-06-0639264[autopull] Upgrade base image to v1.2.2
1.0.02024-04-3036878Migrate to low code
0.2.62024-05-1738330Updating python dependencies
0.2.52024-01-1134154prepare for airbyte-lib
0.2.42023-11-2432837Handle 403 error
0.2.32023-06-1927471Update CDK to 0.40
0.2.22023-06-0627007Update CDK
0.2.12023-03-2024217Certify to Beta
0.2.02023-03-1424005Enable in Cloud
0.1.02021-11-1118666🎉 New Source - Xero [python cdk]