Docs/Connectors

Xero

Invoices, bank transactions and journals from one Xero organisation, pulled incrementally by last update.

The xero connector reads accounting data from one Xero organisation.

Connector name xero
Products Records
Credentials A Xero app's client ID and secret, plus a refresh token for a standard app
Scopes accounting.transactions.read, accounting.journals.read, and offline_access for a refresh token

What it pulls

Object Contents
invoice Type, number, reference, contact ID and company, dates, due date, status, subtotal, tax, total, amounts due, paid and credited, currency, paid-on date, last update
invoice_line Description, quantity, unit amount, item code, account code, tax type, tax amount and line amount, linked to the invoice
bank_transaction Type, contact ID and company, bank account code, date, reference, status, reconciled flag, totals, currency, last update
bank_transaction_line The same line fields, linked to the bank transaction
journal_line Journal number and date, reference, source type, account code, type and name, description, net, gross and tax amounts, tax name

Choose a subset with the objects option: invoices, bank_transactions, journals. All three are pulled by default.

Contact names in contact_company become ORG_ tokens. Descriptions are treated as free text and redacted. See How scrubbing works.

Credentials

Xero access tokens expire after 30 minutes, so a scheduled run needs a way to get new ones. There are two:

  • Custom connection. A Xero custom connection app is tied to one organisation. Give the SDK its clientId and clientSecret, and it requests a fresh token on each run. No tenantId is needed.
  • Standard app with a refresh token. Give the SDK the app's clientId and clientSecret, a refreshToken, and the tenantId of the organisation to read (listed at https://api.xero.com/connections). When Xero issues a new refresh token, the SDK saves it so the next run still works.

You can also pass a short-lived accessToken for a one-off run.

Grant the app accounting.transactions.read and accounting.journals.read, plus offline_access for a standard app so Xero issues a refresh token. Nothing else is needed, and the connector never writes to Xero.

Connect

bash
datayield connect xero --name xero-uk -o tenantId=<tenant id> -o clientId=<client id> \
  -o clientSecret=env:XERO_CLIENT_SECRET -o refreshToken=env:XERO_REFRESH_TOKEN

Secret options passed directly are saved to ~/.datayield/credentials. Values written as env:NAME are read from the environment at run time, which suits CI. See CLI reference.

Options

Option Required Meaning
clientId with clientSecret The Xero app's client ID
clientSecret with clientId The app's client secret. Stored as a secret.
refreshToken standard apps Stored as a secret, and updated when Xero rotates it
tenantId standard apps The organisation to read
accessToken instead of the above A current access token, for a one-off run
objects no invoices, bank_transactions, journals. Defaults to all three.

New records on each run

Invoices and bank transactions are requested with If-Modified-Since set to the last successful run, and filtered by their last update time. Journals are filtered by their creation time. An invoice edited after it was first sent is sent again with its new values.

Dates

The connector converts Xero's own date format to ISO timestamps before scrubbing, so the scrubber reads every date column the same way.