Xero

Fetch bank transactions and bank transfers from Xero.

Setup

Create a Xero app at developer.xero.com and complete the OAuth 2.0 flow. Save your credentials to a JSON file:

{
  "client_id": "...",
  "client_secret": "...",
  "access_token": "eyJ...",
  "refresh_token": "...",
  "tenant_id": "..."
}

VisiGrid automatically refreshes expired access tokens and writes the updated credentials back to the file.

Usage

vgrid fetch xero --credentials xero-creds.json --account "Business Account" \
  --from 2026-01-01 --to 2026-02-01 --out xero.csv

To fetch only transactions or only transfers:

vgrid fetch xero --credentials xero-creds.json --account "Business Account" \
  --include transaction --from 2026-01-01 --to 2026-02-01 --out xero.csv

Options

Flag	Description	Default
--from	Start date inclusive (YYYY-MM-DD)	required
--to	End date exclusive (YYYY-MM-DD)	required
--credentials	Path to OAuth2 JSON file	—
--access-token	Direct access token (requires --tenant-id)	—
--tenant-id	Xero tenant ID	—
--account	Bank account name (resolved to AccountID)	—
--account-id	Bank account ID directly	—
--include	Entity types to fetch	transaction,transfer
--out	Output CSV path	stdout
-q / --quiet	Suppress progress messages	off

Type mapping

Xero entity	Type	Canonical type
BankTransaction	RECEIVE	deposit
BankTransaction	SPEND	expense
BankTransaction	other	other
BankTransfer	from our account	transfer (negative)
BankTransfer	to our account	transfer (positive)

Date handling

• effective_date — parsed from Xero’s /Date(millis+offset)/ format, converted to YYYY-MM-DD. Falls back to DateString if Date is absent.
• posted_date — same as effective_date (Xero does not distinguish)

Notes

Account resolution. --account filters by Name and Type=="BANK". Double quotes in account names are escaped automatically.

Transfer deduplication. VisiGrid queries transfers by both FromBankAccount and ToBankAccount, then deduplicates by BankTransferID.

source_id format. banktxn:{id} for transactions, transfer:{id} for transfers.

Pagination. Page-based (100 items per page). Stops when a page returns fewer items than the page size.

Sort order. effective_date ascending, then source_id ascending.