How to bulk record payments in Xero from a CSV file

If you need to bulk record payments in Xero from a CSV, for example a remittance list from a customer, a payment run made in your bank, or invoices that were paid in another system, you will find that Xero does not import payments on existing invoices from a file in its own screens. This guide shows the by-hand way, the CSV layout that works, and how Paysweep reads that file and records the payments for you, with a preview first and an undo afterwards.

Last checked 25 Oct 2026 against Xero’s published API description.

What Xero offers on its own

In Xero you record a payment from the invoice or bill itself, one at a time. For several bills Xero also has batch payments (check the menu in your Xero). Neither takes a file. A bank statement import brings in statement lines to reconcile, not payments against your invoices. So a list of payments in a spreadsheet goes in by hand, or through Xero’s API.

The by-hand way

Open each invoice or bill, go to the payment section, enter the amount, the date and the bank account, and save. For a handful of payments this is fine. For a remittance list of two hundred invoices, or a clean-up of old open invoices, it is hours of the same four fields, and one slip means a payment on the wrong invoice.

The CSV layout

Use one row per payment. These are the columns Paysweep understands:

• Invoice number. The invoice or bill number as it is in Xero. Or InvoiceID, Xero’s own ID, if you have it.
• Amount. Optional. Blank pays the full amount due.
• Payment date.
• Account code. The bank account the money went into or came out of, or another account set to accept payments. Optional if you set a default on the page.
• Reference. Optional.
• Currency rate. Optional, for invoices in a foreign currency.

Example, three payments:

Invoice Number,Amount,Payment Date,Account Code,Reference
INV-0412,1412.50,2026-10-20,090,Remittance 18 Oct
INV-0415,,2026-10-20,090,Remittance 18 Oct
BILL-7781,396.00,2026-10-21,090,Supplier run

A worked example

Take a remittance with forty invoices from one customer. Thirty-eight are paid in full, one is paid in part, and one was already paid last week. Put the forty rows in a file, leave the amount blank for the full payments and write the part amount on its row. The preview shows thirty-nine payments ready, the total, and one row to fix: the invoice that has nothing due. You fix or remove that row, or simply run the thirty-nine.

Common file problems

• Date formats. A date such as 03/04/2026 can mean the third of April or the fourth of March. On the page you choose whether your file uses year-month-day, day-month-year or month-day-year. Year-month-day is the safest format to write.
• Decimal commas and symbols. Amounts such as 1.234,50 or £1,234.50 are read. More than two decimals is a row to fix.
• Numbers that match two documents. If an invoice number is used twice in Xero, use the InvoiceID for that row.
• Lock date. A payment dated on or before your lock date is a row to fix.
• Blank rows. Empty rows are skipped. Row numbers keep counting, so a row number in an error message is still the row you see in your spreadsheet program.
• File size. A file can hold up to 5,000 rows and one run can record up to 2,500 payments. Larger loads go in several files.

Doing it with Paysweep

1. Prepare the file. One row per payment, with the columns listed above. Several rows for the same invoice are fine.
2. Connect your organisation. Sign in to Paysweep and connect the Xero organisation the invoices belong to.
3. Upload the CSV. Paysweep maps the columns by their headers. Fix the mapping by hand if a header was not recognised, and set a default account code if your file has none.
4. Read the checks. Rows with a problem are listed with the row number from your file. They are never sent.
5. Check the preview. The ready payments are counted, with the total per currency.
6. Confirm. Type PAY and the number of payments. The number is checked against the preview.
7. Open the result. Each row is listed with its outcome and a link to the invoice or bill in Xero.

Fixing errors and trying again

The rows to fix can be downloaded as a CSV file. Their row numbers match your original file, so you can correct the cells in the original and upload it again. Previews are free and unlimited, so uploading the same file several times while you clean it costs nothing.

What to expect

Each payment is a separate call to Xero (PUT /Payments) sent with a fixed idempotency key, so a retry never records a second payment. Before it, the invoice is read again; after it, the payment is read back. Xero allows about 60 calls a minute, so a few hundred payments take several minutes. Xero’s API is described in XeroAPI/Xero-OpenAPI.

Connecting, uploading and previewing are free, and so are the first 3 payments in each organisation. After that a $39 one-off pass covers one organisation for 7 days and up to 300 payments, and $19 a month per organisation has no limit; both prices are excl. VAT/sales tax. See pricing. To clear many old invoices at once, read how to mark invoices as paid in bulk in Xero.

Questions

Related guides

• How to mark invoices as paid in bulk in Xero
  Clearing many old open invoices and bills against one account from an Excel or CSV list, with a preview first.
• How to undo bulk payments in Xero
  Removing payments by hand, and how Paysweep undo works within 30 days and what it leaves alone.
• Pricing
  Free previews, a $39 pass or $19 a month, excl. VAT/sales tax.
• Paysweep overview
  What Paysweep does with your file, the checks on every step, and how undo works.