Browse documentation

Invoice import

Developer > Import data > Invoice import. Choose which invoice formats the Entity accepts, then map each one. A mapping says which column or tag of your file is the invoice number, the date, the amount, and so on.

It applies to every import of that format: from the app, from the API, and from the SFTP inbox. You map once, then every later file is read the same way.

The Invoice import page: an SFTP file prefix field with invoices-, the format buttons CII, UBL, CSV and JSON with CSV selected, an upload zone with a CSV file name, a Search a column field and a Save button, and on the right an Already mapped list that links each file column, such as invoice_number or amount_excl_vat, to an Invunion field with a sample value

Map a format

  1. Choose the Format: CII, UBL, CSV or JSON.
  2. Drop a sample file in the upload zone, or click to choose one. Invunion lists its columns or tags.
  3. Link each column or tag to an Invunion field. Use Search a column to find one in a long list.
  4. Select Save.

Mappings you already saved stay listed on the right, under Already mapped. Each line shows the column of your file, a sample value, and the Invunion field it feeds. Select the X to remove a line.

The invoice fields

Invunion fieldWhat it holds
Invoice no.The invoice number.
Issue dateThe date the invoice was issued.
Due dateThe date payment is due.
Counterparty (customer/supplier)Who the invoice is for. See below.
DescriptionA free text.
Amount excl. VAT, VAT amount, Amount incl. VATThe three amounts of the invoice.
CurrencyThe currency code, such as EUR.
External ref.The invoice’s own reference in your system.
Payment methodFor example transfer.
Type (invoice/credit_note)Whether the line is an invoice or a credit note.
StatusFor example unpaid.

For CSV and JSON, map your own columns to these fields. For UBL and CII, the standard fields are already mapped, so you only add the extra ones.

Find the counterparty

Invunion needs to know who each invoice is for. Map one of these, and it finds the counterparty or creates it:

  • a customer code,
  • a counterparty external reference,
  • a VAT number,
  • or a name, as in the example above.

The invoice’s own External ref. is not a counterparty key. It identifies the invoice, not who it is for.

Extra tags in UBL and CII

Upload a sample invoice to see all its tags. Map an extra tag to an invoice field, or to a metadata key of your choice. A metadata key has 1 to 64 letters, digits, dots, underscores or hyphens. Invunion rejects an XML file that is neither UBL nor CII, and a ZIP without XML files.

SFTP file prefix

The SFTP file prefix limits which files of the SFTP inbox are read as invoices. In the example the prefix is invoices-, so invoices-2026-10.csv is imported and export.csv is not. Leave it empty to read every file. See Automatic statements for how files arrive.

Limits to keep in mind

  • Excel workbooks and PDF invoices are not accepted. Export to CSV first.
  • A mapping applies to one format. CSV and JSON need their own.
  • A sandbox Entity is the safest place to try a new mapping.

Updated · View as Markdown