You have spent the last hour transcribing a stack of supplier invoices into a spreadsheet, saved it as a CSV, and uploaded it to Xero—only to be stopped dead by this prompt:
"Import Failed: Missing mandatory column header."
When month-end reconciliations are on the line, diagnosing spreadsheet syntax errors is the last thing you want to do.
This error occurs when Xero’s automated file parser checks line 1 of your spreadsheet and fails to find an exact match for one or more required fields. If a required header contains a missing asterisk, an extra whitespace character, a typo, or altered capitalization, Xero halts the upload and rejects the entire batch.
Follow this quick guide to diagnose why Xero rejected your file, apply the 60-second fix, and automate the pipeline so you never face broken CSV imports again.
What Are the Mandatory Column Headers for Xero Bill Imports?
When importing supplier bills (Accounts Payable) into Xero via CSV, line 1 of your file must contain the following core column headers:
- *ContactName – The vendor or supplier name.
- *InvoiceNumber – The unique bill or invoice reference.
- *InvoiceDate – The issue date matching your organization’s date format.
- *DueDate – The payment deadline date.
- *UnitAmount – The net unit cost or item amount (numbers only, no currency signs).
- *AccountCode – The general ledger code from your Chart of Accounts.
- *TaxType – The exact tax rate label configured in your Xero settings.
(Optional but strongly recommended columns include Description, Quantity, and TrackingName1 / TrackingOption1.)
For step-by-step CSV formatting guidelines, refer to the official Xero Central guide on importing bills and credit notes.
The 4 Hidden Causes Behind the "Missing Mandatory Column Header" Error
If your spreadsheet appears complete at first glance, one of these four common formatting traps is almost certainly the culprit:
1. The Stripped Asterisk Trap (ContactName vs. *ContactName)
In Xero's official template schema, mandatory fields are designated with a leading asterisk (*). If your data was exported from a third-party app or typed manually without the asterisk, Xero’s parser will reject the line because ContactName does not match the expected string *ContactName.
2. Invisible Trailing Spaces
A stray space at the end of a header name (for instance, "ContactName " or "*UnitAmount ") will cause the match to fail. Because spreadsheet cells visually hide trailing spaces, the header looks correct on screen while failing the backend validation check.
3. Microsoft Excel Auto-Formatting and Delimiter Quirks
Opening and saving CSV files in Microsoft Excel can introduce subtle corruptions:
- Excel may change standard comma delimiters to semicolons based on regional operating system settings.
- It may add invisible Byte Order Marks (BOM) or wrap headers in redundant double-quote marks.
- It often strips leading zeros from account codes (turning account 0200 into 200, creating subsequent mapping failures).
4. Mismatched Schemas (Bills vs. Sales Invoices)
Xero uses distinct import structures for Bills to Pay (Accounts Payable) and Sales Invoices (Accounts Receivable). If you attempt to upload a file containing sales invoice headers into the Bills section (or vice-versa), Xero flags missing column headers immediately.
The 60-Second Step-by-Step Fix
To clean your file and pass Xero validation on the next try:
Step 1: Open Your CSV in a Plain Text Editor
Do not open the file in Excel. Instead, right-click your .csv file and open it with Notepad (Windows) or TextEdit (Mac). This reveals the raw characters, delimiters, and quotation marks without spreadsheet auto-formatting.
Step 2: Replace Line 1 with the Verified Header String
Delete your existing first line and paste this standard header sequence directly into line 1:
*ContactName,*InvoiceNumber,*InvoiceDate,*DueDate,Description,Quantity,*UnitAmount,*AccountCode,*TaxType
Step 3: Spot-Check Dates and Currencies
Ensure your data rows align with the columns:
- Dates: Ensure dates match your regional Xero settings (e.g., DD/MM/YYYY or MM/DD/YYYY).
- Amounts: Remove all currency symbols (
$,£,€) and thousands commas. Use plain decimals (e.g., 1250.00). - Tax Labels: Ensure the text in *TaxType matches your Xero tax rates verbatim (e.g., 20% (VAT on Expenses) or Tax Exempt (0%)).
Step 4: Save with UTF-8 Encoding
In your text editor, select File > Save As. Ensure the file format is set to CSV (Comma delimited) and the encoding is set to UTF-8.
Return to Xero, upload the saved file, and the error will be resolved.
Complete Xero Bill Import Field Reference
Use this reference table to ensure every column in your import file meets Xero's validation criteria:
| Column Header | Status | Format / Validation Rule | Example |
|---|---|---|---|
| *ContactName | Required | Text (Must match or create a Xero contact) | Acme Supplies Ltd |
| *InvoiceNumber | Required | Alphanumeric (Vendor reference number) | INV-2026-104 |
| *InvoiceDate | Required | DD/MM/YYYY or MM/DD/YYYY | 15/09/2026 |
| *DueDate | Required | DD/MM/YYYY or MM/DD/YYYY | 30/09/2026 |
| Description | Recommended | Text describing the specific line item | Server Maintenance - Q3 |
| Quantity | Optional | Number / Decimal (Defaults to 1 if empty) | 1 |
| *UnitAmount | Required | Decimal number (No symbols or commas) | 850.00 |
| *AccountCode | Required | Valid Chart of Accounts numeric code | 400 |
| *TaxType | Required | Exact tax rate label from Xero | 20% (VAT on Expenses) |
Stop Fixing CSVs Manually: Automate Invoice Extraction
Manually retyping line items, verifying tax codes, and adjusting column headers across 30 to 50 client invoices every month is slow and error-prone.
If you want to skip spreadsheet triage entirely, try Sync2Zero.
Sync2Zero uses multimodal AI extraction powered by Google Gemini to convert messy invoice PDFs and receipt images directly into verified, pre-mapped files:
- No Template Rules: Upload scanned receipts, multi-page PDFs, or digital invoices without training custom templates.
- In-Browser Verification: Review line items, adjust account codes, and confirm totals in an interactive data grid before exporting.
- Pre-Mapped Xero Schemas: Exports clean CSV and Excel files formatted to Xero's required structure on the first attempt—no missing asterisks or syntax errors.
- 1 Invoice = 1 Scan: Multi-line invoices never trigger credit penalties.
Frequently Asked Questions:
Frequently Asked Questions
Convert your first 2 invoices completely free with no signup or credit card required at sync2zero.com.
