This tool reads the trial balance from Xero’s reporting API and writes consistent CSV columns for account codes, names, monthly movements and year-to-date balances.
Before anything is written to disk, it runs a balance check: both the
current month’s movement and the year-to-date figures must balance, or
no file is written. One limit: --date is an as-at date, not
a range. Xero’s Trial Balance endpoint accepts only a date, so the Trial
Balance by Date Range report, which exists in the Xero interface only,
cannot be reproduced this way. The movement columns cover the usual
reason for wanting a range: the current month.
What this tool does
- Pulls a trial balance from Xero’s own reporting API into a tidy CSV that Power BI, Excel or pandas loads without clean-up.
- Refuses to write a file unless both the month’s movement and the year-to-date figures balance.
Related work: XeroAPI accepted my correction to its command-line report flags. It maps --standard-layout and --payments-only to the matching SDK parameters for balance sheet and profit and loss reports. That contribution concerns a separate tool; it does not validate this exporter. Read the accepted-work record.
Limits
Read-only (accounting.reports.trialbalance.read); this tool cannot write to any ledger.
MIT-licensed utility code, no warranty; outputs feed professional review like any other workpaper input. Not affiliated with or endorsed by Xero.
Get it
Needs Python 3.10 or later and a free Xero developer app, about 5 minutes of one-off setup. It works with Xero’s free Demo Company, so nothing has to touch a live ledger. A command-line tool for whoever runs Python at your firm.
git clone https://github.com/ryanduguid/accounting-review-pipeline.git
git -C accounting-review-pipeline checkout xero-trial-balance-export/v0.1.6
cd accounting-review-pipeline/packages/xero-trial-balance-export
python -m pip install --require-hashes -r requirements.lock
# copy .env.example to .env and add the app's client ID and secret, then:
python auth.pyFirst success takes one command. After the one-off consent step above, export a dated trial balance:
python export_tb.py --date 2026-06-30
# writes a CSV such as demo-company-au-...-tb-2026-06-30-accrual.csv, only when both balance checks passSoftware issue using fictional data? Open an issue or email with the tool named in the subject. If the email link does not open, the contact page spells the address out.
Synthetic worked example
Reproduce the Xero trial balance integrity evaluation
These release xero-trial-balance-export/v0.1.6 tests use mocked Xero API behaviour and synthetic account rows. They do not contain a live organisation’s data.
| Outcome | Synthetic facts | Test-backed result |
|---|---|---|
| Balanced, CSV written | Business Bank Account (090) has a $1,200.00 movement debit and $15,234.50 YTD debit. Trade Debtors (610) has equal credits. | Both pairs balance and the exact expected CSV bytes are written. |
| Unbalanced, CSV refused | Cash (090) has $100.00 movement and YTD debits. Equity (960) has a $100.00 movement credit but only a $90.00 YTD credit. | The movement balances, but the $10.00 YTD difference causes exit code 1 and no CSV file output. |
The tagged balanced-output test pins the CSV bytes. The tagged unbalanced-YTD test pins the refusal and warning. Refused means no CSV file output; the diagnostic warning is still printed.
The tool remains read-only and cannot write to a ledger. Its output is a review aid, not advice or a compliance result. It does not post entries, approve work, lodge returns or lock periods.
Common questions
Can it export a trial balance for a date range?
No. Xero’s Trial Balance endpoint accepts an as-at date, not a range, so the Trial Balance by Date Range report, which exists in the Xero interface only, cannot be reproduced this way. The movement columns cover the usual reason for wanting a range, which is the current month.
Can this tool change my Xero data?
No. It requests the accounting.reports.trialbalance.read scope, which is read-only, so it cannot write to any ledger.
What happens if the trial balance does not balance?
No file is written. The balance check runs before anything reaches disk, and both the month’s movement and the year-to-date figures have to balance for the export to proceed.