Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mage.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Configuration

To set up the Xero source, provide the following configuration parameters:
KeyDescriptionSample ValueRequired
client_idClient ID issued when you create your Xero app.abcdefg✅
client_secretClient secret generated when you create your Xero app.abcdefg✅
tenant_idTenant ID associated with your Xero organization.abcdefg✅
start_dateThe start date for syncing data. Format: YYYY-MM-DDTHH:MM:SSZ.2021-01-01T00:00:00Z✅
refresh_tokenOAuth refresh token (required if refresh_token_secret_name is not provided).abcdefg⚠️
refresh_token_secret_nameName 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.
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:
StreamPrimary KeyReplication Key
accountsAccountIDUpdatedDateUTC
bank_transactionsBankTransactionIDUpdatedDateUTC
bank_transfersBankTransferIDCreatedDateUTC
contactsContactIDUpdatedDateUTC
credit_notesCreditNoteIDUpdatedDateUTC
employeesEmployeeIDUpdatedDateUTC
expense_claimsExpenseClaimIDUpdatedDateUTC
invoicesInvoiceIDUpdatedDateUTC
itemsItemIDUpdatedDateUTC
journalsJournalIDJournalNumber
linked_transactionsLinkedTransactionIDUpdatedDateUTC
manual_journalsManualJournalIDUpdatedDateUTC
overpaymentsOverpaymentIDUpdatedDateUTC
paymentsPaymentIDUpdatedDateUTC
prepaymentsPrepaymentIDUpdatedDateUTC
purchase_ordersPurchaseOrderIDUpdatedDateUTC
quotesQuoteIDUpdatedDateUTC
receiptsReceiptIDUpdatedDateUTC
usersUserIDUpdatedDateUTC

​
Full Table Streams

These streams are fully synced on each run (no incremental support):
StreamPrimary Key
branding_themesBrandingThemeID
contact_groupsContactGroupID
currenciesCode
organisationsOrganisationID
repeating_invoicesRepeatingInvoiceID
tax_ratesTaxType
tracking_categoriesTrackingCategoryID

​
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:
ScopeRequired For
accounting.settings.readOrganisation settings, currencies, etc.
accounting.transactions.readInvoices, bank transactions, payments
accounting.contacts.readContacts
accounting.reports.readReports
accounting.journals.readJournals
accounting.attachments.readAttachments
offline_accessLong-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"
  1. 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.