Xero

Sync accounting data from Xero including invoices, contacts, payments, and more. Supports incremental syncing with automatic OAuth token refresh.

Only in Mage Pro.

Try our fully managed solution to access this advanced feature.

 

Get started for free

Configuration

To set up the Xero source, provide the following configuration parameters:

Key	Description	Sample Value	Required
client_id	Client ID issued when you create your Xero app.	abcdefg	✅
client_secret	Client secret generated when you create your Xero app.	abcdefg	✅
tenant_id	Tenant ID associated with your Xero organization.	abcdefg	✅
start_date	The start date for syncing data. Format: YYYY-MM-DDTHH:MM:SSZ.	2021-01-01T00:00:00Z	✅
refresh_token	OAuth refresh token (required if refresh_token_secret_name is not provided).	abcdefg	⚠️
refresh_token_secret_name	Name of the Mage secret containing the refresh token (recommended for production).	XERO_REFRESH_TOKEN	⚠️

You must provide either refresh_token or refresh_token_secret_name. Using refresh_token_secret_name is recommended because Xero uses rotating refresh tokens (each token can only be used once), and this option automatically persists the new token after each refresh.

Option 1: Direct Refresh Token

client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
tenant_id: YOUR_TENANT_ID
start_date: "2021-01-01T00:00:00Z"
refresh_token: YOUR_REFRESH_TOKEN

Xero refresh tokens are single-use. Each time the token is refreshed, a new one is issued and the old one is invalidated. With this option, the new token is only stored in memory during the sync, so subsequent pipeline runs may fail if the token has been rotated.

Option 2: Mage Secret (Recommended)

client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
tenant_id: YOUR_TENANT_ID
start_date: "2021-01-01T00:00:00Z"
refresh_token_secret_name: XERO_REFRESH_TOKEN

First, create a secret in Mage. You can choose any name for your secret:

1. Open a pipeline edit page
2. Expand the right side panel
3. Click the “Secrets” tab
4. Click “Add new secret”
5. Enter your chosen secret name (e.g., XERO_REFRESH_TOKEN) and your initial refresh token as the value
6. Copy the secret name to your Xero config’s refresh_token_secret_name field

The tap will automatically update the secret with the new refresh token after each sync, ensuring reliable long-term operation.

Supported Streams

The Xero source supports the following streams:

Incremental Streams

These streams support incremental syncing based on the start_date configuration and bookmark state:

Stream	Primary Key	Replication Key
accounts	AccountID	UpdatedDateUTC
bank_transactions	BankTransactionID	UpdatedDateUTC
bank_transfers	BankTransferID	CreatedDateUTC
contacts	ContactID	UpdatedDateUTC
credit_notes	CreditNoteID	UpdatedDateUTC
employees	EmployeeID	UpdatedDateUTC
expense_claims	ExpenseClaimID	UpdatedDateUTC
invoices	InvoiceID	UpdatedDateUTC
items	ItemID	UpdatedDateUTC
journals	JournalID	JournalNumber
linked_transactions	LinkedTransactionID	UpdatedDateUTC
manual_journals	ManualJournalID	UpdatedDateUTC
overpayments	OverpaymentID	UpdatedDateUTC
payments	PaymentID	UpdatedDateUTC
prepayments	PrepaymentID	UpdatedDateUTC
purchase_orders	PurchaseOrderID	UpdatedDateUTC
quotes	QuoteID	UpdatedDateUTC
receipts	ReceiptID	UpdatedDateUTC
users	UserID	UpdatedDateUTC

Full Table Streams

These streams are fully synced on each run (no incremental support):

Stream	Primary Key
branding_themes	BrandingThemeID
contact_groups	ContactGroupID
currencies	Code
organisations	OrganisationID
repeating_invoices	RepeatingInvoiceID
tax_rates	TaxType
tracking_categories	TrackingCategoryID

How to Generate Credentials

To use this source, you need to create a Xero OAuth app and complete the OAuth flow.

1. Create a Xero App

Go to the Xero Developer Portal and create a new app. Note down your Client ID and Client Secret.

2. Configure OAuth2 Scopes

When setting up your Xero app, grant the following OAuth2 scopes:

Scope	Required For
accounting.settings.read	Organisation settings, currencies, etc.
accounting.transactions.read	Invoices, bank transactions, payments
accounting.contacts.read	Contacts
accounting.reports.read	Reports
accounting.journals.read	Journals
accounting.attachments.read	Attachments
offline_access	Long-lived access via refresh tokens

• The minimum scope required for discovery is accounting.settings.read.
• You only need scopes for the streams you plan to sync.
• Missing scopes for a selected stream will result in 401 or 403 errors.

Example Scope String:

accounting.settings.read accounting.transactions.read accounting.contacts.read accounting.reports.read accounting.journals.read accounting.attachments.read offline_access

3. Complete the OAuth2 Authorization Flow

Follow Xero’s OAuth2 Auth Flow Guide to obtain your initial access_token and refresh_token.

Make sure to request the offline_access scope to receive a refresh token.

4. Get Your Tenant ID

The tenant_id uniquely identifies your Xero organization. After completing OAuth authentication:

1. Call the connections endpoint:

curl -X GET "https://api.xero.com/connections" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

2. Extract the tenantId from the response:

[
  {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "tenantType": "ORGANISATION",
    "tenantName": "Your Company Name"
  }
]

If your app is connected to multiple Xero organizations, the response will contain multiple entries. Choose the tenantId for the organization you want to sync data from.