How to rename csv column headers to match xero's bank import format
- Step 1Note Xero's required and optional column names — In Xero: Accounting → Bank accounts → (your account) → Manage Account → Import a Statement. Xero needs at minimum a Date column and an Amount column. Optional columns it recognises: Payee, Description, Reference, Cheque Number. Xero expects a single signed
Amountcolumn (money out negative), not separate debit/credit columns. - Step 2Download the statement CSV from your bank — Export the period you want to import from your online banking portal as CSV. Save it as
.csv(the tool also reads.tsvand.txt). Confirm the first row is the header row — that's what the tool reads to build the rename list. - Step 3Drop the statement onto the tool above — PapaParse parses it in your browser and lists each bank column with a rename box. The displayed header is trimmed of surrounding spaces for readability, but the rename writes exactly what you type.
- Step 4Type the Xero name next to each bank column — For example
Transaction Date→Date,Net Amount→Amount,Narrative→Description,Merchant→Payee. Leave a box blank to keep a column you don't need to relabel. - Step 5Run and download the renamed CSV — The button reads
Rename N headers. The result shows Headers renamed, Data rows, and a 10-row preview so you can confirm the Date and Amount columns now carry the right names. Click Download for<name>.renamed.csv. - Step 6Import into Xero and confirm the column mapping — Use Import a Statement, upload the renamed CSV, and check the mapping summary. With matching headers, Date and Amount should be pre-assigned. Confirm the date format Xero infers matches your bank's (DD/MM/YYYY vs MM/DD/YYYY) before you finish the import.
Bank header to Xero name — common renames
Typical bank statement headers and the Xero name to rename them to. Banks vary; match against your own export and Xero's Import a Statement screen.
| Bank exports it as | Rename to (Xero) | Required? | Notes |
|---|---|---|---|
Transaction Date, Posting Date, Date Posted | Date | Yes | Xero needs exactly one Date column |
Net Amount, Value, Amount (GBP) | Amount | Yes | Single signed column — money out is negative |
Debit + Credit (two columns) | — (cannot rename into one) | Yes (combined) | Xero wants one Amount column; renaming can't merge two — see edge cases |
Narrative, Details, Memo | Description | Optional | Free-text transaction description |
Merchant, Counterparty, Name | Payee | Optional | Who the transaction was with |
Reference, Ref, Customer Ref | Reference | Optional | Often already matches — leave blank |
Cheque No, Check Number | Cheque Number | Optional | Only relevant for cheque transactions |
What the rename can and cannot fix for a Xero import
Header rename solves naming mismatches only. Anything that requires changing cell values or the number of columns needs a different tool or a pre-step.
| Problem | Rename fixes it? | What to do otherwise |
|---|---|---|
Header is Transaction Date, Xero wants Date | Yes | Rename the column |
Two columns: Debit and Credit | No | Combine into one signed column upstream (spreadsheet formula), then rename to Amount |
| Date stored as MM/DD/YYYY but bank is UK | No | Xero asks you to pick the date format on import — set it there |
Amount has a £ symbol or thousands commas | No | Use csv-find-replace to strip £ and commas before importing |
| Extra columns Xero ignores (Balance, Type) | Leave as-is | Xero ignores unmapped columns; or drop with csv-column-remover |
Cookbook
Real bank-statement header rows before and after. Amounts and dates shown to prove they pass through unchanged.
UK bank: Transaction Date and Net Amount
ExampleA common UK current-account export. Xero rejects it because there is no Date or Amount column by those names. Two renames fix it; the signed amounts pass through.
Input header: Transaction Date,Net Amount,Narrative,Balance 10/06/2026,-42.50,TESCO STORES 2345,1284.10 Renames typed: Transaction Date -> Date Net Amount -> Amount Narrative -> Description Balance -> (blank, kept; Xero ignores it) Output header: Date,Amount,Description,Balance 10/06/2026,-42.50,TESCO STORES 2345,1284.10
Add Payee and Reference for richer reconciliation
ExampleA statement that already has a Date column but uses bank-specific names for the rest. Renaming Merchant → Payee gives Xero a payee to match reconciliation rules against.
Input header: Date,Amount,Merchant,Ref 09/06/2026,1500.00,ACME PAYROLL,INV-2210 Renames typed: Date -> (blank, already matches) Merchant -> Payee Ref -> Reference Output header: Date,Amount,Payee,Reference 09/06/2026,1500.00,ACME PAYROLL,INV-2210
Two columns share the header 'Amount'
ExampleSome exports include a posted amount and a running amount, both labelled Amount. Because rename works by position, you can keep one as Amount and relabel the other so Xero doesn't grab the wrong one.
Input header: Date,Amount,Amount 08/06/2026,-19.99,1264.11 Renames typed (by column position): column 2 Amount -> Amount (the transaction value) column 3 Amount -> Balance (the running balance) Output header: Date,Amount,Balance 08/06/2026,-19.99,1264.11
Reference column already correct — rename nothing extra
ExampleWhen only the Date and Amount headers are wrong, leave every other box blank. The renamed-count confirms you changed exactly two headers.
Input header: Posting Date,Value,Description,Reference Renames typed (others blank): Posting Date -> Date Value -> Amount Output header: Date,Amount,Description,Reference → Headers renamed: 2
Why a debit/credit split needs a pre-step
ExampleXero wants one signed Amount column. Renaming cannot merge two columns into one — this is the most common case where header rename alone isn't enough.
Input header (cannot be fixed by rename alone): Date,Debit,Credit,Description 10/06/2026,42.50,,TESCO 09/06/2026,,1500.00,PAYROLL Pre-step in your spreadsheet: make one column Amount = Credit - Debit -> -42.50, 1500.00 Then import the single-Amount file and rename headers if needed. Header rename moves names, not values across columns.
Errors and edge cases
Real errors and silent failures sourced from each platform's own documentation. Match the wording to the row, fix what the row says to fix.
Bank splits money into Debit and Credit columns
Cannot merge — rejectedXero's manual import needs a single signed Amount column (money out negative). Renaming a header cannot combine two columns into one. Build a single Amount column upstream (in your spreadsheet, Amount = Credit - Debit), then come back and rename headers if any others are off. This tool moves column names, not values between columns.
Date format mismatch (DD/MM vs MM/DD)
Preserved — set on importThe rename never touches date values, so 10/06/2026 stays exactly as exported. Xero asks you to choose the date format on the Import a Statement screen — pick DD/MM/YYYY for UK/AU/NZ banks or MM/DD/YYYY for US. A wrong choice there reads day 10 as October; that's a Xero setting, not a rename problem.
Amount column carries a currency symbol or thousands commas
Import may rejectXero expects a plain number in Amount. £1,500.00 can fail to parse. Header rename doesn't change cell values, so strip the symbol and commas first with csv-find-replace (replace £ and , with nothing in the amount column), then rename headers and import.
Statement uses a semicolon delimiter (EU locale)
SupportedPapaParse auto-detects the delimiter, so a semicolon-separated export from a European bank parses and lists its columns correctly. The download is written as a standard comma-delimited CSV, which Xero's importer accepts.
Extra columns like Balance or Type left in the file
By designXero ignores columns it doesn't recognise, so leaving Balance, Type, or Category in place won't break the import — leave their rename boxes blank. If you prefer a minimal file, drop them with csv-column-remover after renaming.
First data row is actually a sub-header or metadata line
Mis-detected headerSome banks prepend an account-summary row before the real headers, so the tool reads that summary as the header. Open the CSV and delete the metadata rows above the true header first (or clean it with csv-cleaner), then drop it here so the rename list shows the real column names.
Output has no BOM; opens oddly in Excel afterwards
ExpectedThe download is UTF-8 with no byte-order mark. Xero imports it fine. If you re-open the renamed file in Excel and see odd characters in a payee name, that's Excel guessing the encoding — use Data → From Text/CSV and select UTF-8. The file itself is correct for Xero.
Statement exceeds the free-tier limit
Pro overlayA single month's statement is well within free limits, but a multi-year export can exceed 500 rows or 2 MB, triggering the Pro overlay. Either upgrade (100 MB / 100,000 rows) or import per-month files, which is also how Xero prefers bank statements to be loaded.
Frequently asked questions
What exact headers does Xero require?
At minimum, Xero's Import a Statement needs a Date column and an Amount column. Optional columns it recognises are Payee, Description, Reference, and Cheque Number. Rename your bank's equivalents to these names. The Amount column must be a single signed value (money out negative), not separate debit and credit columns.
Will renaming headers affect my reconciliation?
No. The tool rewrites only the header row. Transaction dates, amounts, payees, and references in the data rows are passed through byte-for-byte, so Xero's reconciliation matching against bank rules and outstanding invoices works exactly as it would on the original export. Only the column labels change.
Does this work for both Xero's manual import and bank feeds?
It's for the manual Import a Statement CSV upload. Automatic bank feeds connect through Open Banking or a direct feed and don't use CSV files at all, so there are no headers to rename there. Use this tool whenever you're importing a statement CSV by hand.
My bank gives me Debit and Credit columns — can I rename them into one Amount?
No. Renaming changes column names, not the data between columns. Xero wants a single signed Amount column. Create that column in your spreadsheet first (for example Amount = Credit − Debit, so money out is negative), save as CSV, then use this tool to rename any remaining headers and import.
The amounts have £ signs and commas — does the tool clean those?
No — it only renames headers, it doesn't edit cell values. Strip the currency symbol and thousands separators first with csv-find-replace (replace £ and , with nothing), then rename Net Amount to Amount and import. Xero needs a plain number in the Amount column.
Xero is reading my dates wrong after import — is the rename to blame?
No. The rename leaves date values untouched. Xero asks you to choose the date format on the import screen; if you pick MM/DD/YYYY for a UK statement, 10/06 becomes October instead of June. Re-run the import and select the correct DD/MM/YYYY format for your region.
Can I leave the columns Xero doesn't need?
Yes. Xero ignores any column whose header it doesn't recognise, so Balance, Type, or Category can stay — just leave their rename boxes blank. If you want a cleaner file, remove them with csv-column-remover after renaming. Neither approach affects the import of Date and Amount.
What file types and delimiters does the tool accept?
It accepts .csv, .tsv, and .txt, and PapaParse auto-detects the delimiter (comma, tab, or semicolon). So a European bank's semicolon export or a tab-separated download both work. The renamed file is always written as a comma-delimited CSV, which Xero's importer expects.
Is there a row or size limit?
Free handles up to 2 MB and 500 data rows per job — fine for a monthly statement. A long multi-year export can exceed that and trigger the Pro overlay; Pro raises the limits to 100 MB and 100,000 rows. Importing one month at a time is also Xero's recommended approach for clean reconciliation.
Does the output add a BOM so it opens cleanly in Excel?
No — the download is UTF-8 with no byte-order mark. Xero reads it correctly. If you later open it in Excel-on-Windows and see odd characters in a payee field, that's Excel's encoding guess; open via Data → From Text/CSV and select UTF-8. The file is correct for Xero regardless.
Is my bank data uploaded to any server?
No. PapaParse processes the file entirely in your browser — account numbers, balances, and payee details never reach a JAD server. Only a usage counter (no content) is recorded when you're signed in, and you can opt out in account settings. The rename adds no exposure of your financial data.
Can I automate the rename for monthly bank imports?
Yes. GET /api/v1/tools/csv-header-rename returns the option schema (a renames map keyed by column index). Pair the @jadapps/runner once and POST your statement CSV to 127.0.0.1:9789/v1/tools/csv-header-rename/run. It runs on your machine, so the bank data stays local — useful for a download → rename → Xero pipeline each month.
Privacy first
Processing runs locally in your browser with PapaParse. No file is uploaded — only metadata counters are saved for signed-in dashboard stats.