Xero

Bring invoices, contacts, payments and the rest of your Xero organisation's accounting data into your warehouse.

Before you start

Xero calls an organisation a tenant. To connect one, you create a custom connection in Xero's developer portal, which gives sanda a client ID and a client secret for that single organisation, and you look up the organisation's tenant ID.

A role that can authorise it. You need to be a Xero adviser or admin for the organisation, because the organisation has to consent to the connection.
A custom connection. In Xero's developer portal, create a new app and choose the Custom connection type. Grant it read-only accounting scopes for the areas you want in sanda, such as invoices, contacts, payments and settings, then authorise it against your organisation. Xero treats custom connections as a premium option and may charge for them, so check its current terms before you create one.
A client ID and secret. Once the connection is authorised, Xero shows the app's client ID and lets you generate a client secret. Xero shows the secret only once, so copy it straight away.
The tenant ID. See the steps below.

Find the tenant ID

The tenant ID is the organisation's identifier in Xero's API. With a custom connection you can read it from Xero's connections endpoint. First ask for an access token, using the client ID and secret:

Get an access token

curl -s -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=YOUR_SCOPES" \
  https://identity.xero.com/connect/token

Replace YOUR_SCOPES with the scopes you granted the app, separated by spaces. The reply holds an access_token. Then list the connected organisations with it:

List the connected organisation

curl -s https://api.xero.com/connections \
  -H "Authorization: Bearer ACCESS_TOKEN"

The tenantId in the reply is the value the form asks for. Access tokens last 30 minutes, so this token is only for looking up the tenant ID. sanda gets its own from the client ID and secret.

Connect Xero

Choose Xero. Go to Data · Connections, press New connection and pick Xero.
Enter the tenant ID. Paste it into Tenant ID. The field is masked, like a password.
Choose how far back to load. Enter a UTC date and time in Start Date, in the form 2022-03-01T00:00:00Z. Xero data created before it is not synced. The start of your financial year, or the day you began using Xero, are common choices.
Choose the authentication method. Authentication Method opens on Bearer Access Token. Change it to OAuth Custom Connection and enter Client ID and Client Secret. See the tip below.
Continue. Press Continue, name the connection, and press Read schema. sanda signs in and lists the areas of Xero it can read. If it fails, the message says why. See Troubleshoot connections.

The rest of the flow, naming the connection, setting a frequency and choosing streams, is the same for every source. See Add a connection.

What syncs

Each area of Xero lands as its own table, so reports can join them cleanly. That includes invoices, contacts, payments and bank transactions. The stream list shows everything the connection can read, and you choose which to sync. See choose what to sync.

Tips

Use OAuth Custom Connection for a connection that keeps running. Bearer Access Token takes a single access token, and Xero access tokens expire after 30 minutes, so syncs would stop working almost at once. It suits a quick test and nothing longer. With OAuth Custom Connection, sanda uses the client ID and secret to get fresh tokens itself.
One connection per organisation. A tenant ID belongs to one Xero organisation. If you have several, add a connection for each and give each a distinct name, for example Acme · Xero (AU). The name decides the tables the rows land in.
Expect a long first load for a large ledger. Xero limits how many API calls an organisation can make each minute and each day, so years of history can take a while. A later Start Date shortens the first run.
Keep the scopes read-only. sanda only ever reads. If a stream fails with a permission error, the app is missing the scope for that area. Add it in the developer portal and authorise the connection again.

Configuration fields

What the connection form asks for. Required fields are marked; the rest are optional.

Field	Type	Required	Description
Tenant ID	string, secret	Yes	Enter your Xero organization's Tenant ID.
Start Date	string	Yes	UTC date and time in the format YYYY-MM-DDTHH:mm:ssZ. Any data with created_at before this date will not be synced.
Authentication Method	one of 2 options	Yes

Authentication Method

Choose one of the following. Each asks for its own fields.

OAuth Custom Connection

Field	Type	Required	Description
Client ID	string	Yes	Your Xero application's Client ID.
Client Secret	string, secret	Yes	Your Xero application's Client Secret.

Bearer Access Token

Field	Type	Required	Description
Access Token	string, secret	Yes	The access token used to call the Xero API.

Something unclear or out of date? Tell us, and we will fix the page.