# 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:

```bash title="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:

```bash title="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

:::steps
1. **Choose Xero.** Go to **Data · Connections**, press **New connection** and pick **Xero**.
2. **Enter the tenant ID.** Paste it into **Tenant ID**. The field is masked, like a password.
3. **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.
4. **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.
5. **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](https://docs.sanda-os.com.au/connections/troubleshooting).
:::

The rest of the flow, naming the connection, setting a frequency and choosing streams, is the same for every source. See [Add a connection](https://docs.sanda-os.com.au/connections/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](https://docs.sanda-os.com.au/connections/choose-streams).

## 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. |


## Related

:::links
- [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes): How sanda reads each stream on every run.
- [Sync schedules](https://docs.sanda-os.com.au/connections/schedules): How often a connection runs.
- [Allowlist sanda’s address](https://docs.sanda-os.com.au/connections/allowlist): For a system behind a firewall.
- [Troubleshoot connections](https://docs.sanda-os.com.au/connections/troubleshooting): What an error means and how to fix it.
:::