Skip to content

CSV import format

Version 1.0

Unlike JSON and XML, CSV in xTool is only an import source. It is not a working format: you cannot choose it when creating a document, store it as document content, send it, or run Format API convert/validate on it as a format code. After a successful import, the document is stored as the internal xTool model (xtool.invoice.1_0 or xtool.credit_note.1_0).

This page is the reference specification for the xTool CSV import format (semicolon-delimited, version 1.0). For how to import invoices via the web app, API, or SFTP, see Import documents.

See also Format models and Invoice model understanding for the internal model that CSV maps to.

1. Changelog

Version Date Description
1.0 2026-08-26 First release of the xTool CSV format. Flat projection of the canonical invoice model xtool.invoice.1_0.

2. Rules

Code lists are taken from the official PEPPOL BIS Billing 3.0 documentation:

https://docs.peppol.eu/poacc/billing/3.0/

Fields marked with an asterisk (*) in the column number are required by the CSV parser and cannot be empty. Target e-invoicing formats (XRechnung, PEPPOL BIS, ZUGFeRD / Factur-X) may require additional fields; missing target-format fields are reported after conversion, not at CSV parse time.

Optional fields that are not used must be left empty. Optional columns may also be omitted from a block’s header row entirely. Optional blocks may be omitted entirely.

File and content rules

  • Encoding must be UTF-8. A UTF-8 BOM is allowed and stripped.
  • One CSV file contains exactly one invoice or credit note.
  • Column separator is a semicolon (;). The separator must not appear inside a column value. Quoting and escaping are not supported.
  • There is no global 50-character limit. Field length limits follow EN 16931 / the target format after conversion.
  • Numbers use a point as decimal separator and no thousands separator: 2450.00. The parser does not limit the number of fractional digits; precision requirements follow the target format after conversion. Amounts typically use 2.
  • Dates use YYYY-MM-DD (ISO 8601), e.g. 2024-06-06.
  • Values are trimmed of leading and trailing whitespace.
  • An empty value means the field is absent.
  • Column names are derived from the canonical model path with dots replaced by underscores, e.g. customer.address_line_1 → customer_address_line_1.
  • The parser reads columns by name, not by position. Column order inside a block and block order in the file do not matter.
  • Unknown column names are rejected. Column names are case-sensitive (Document_Number is not the same as document_number), although block detection is case-insensitive on the first header column. The “Unknown column” error applies to columns within a recognised block; if the first column of a header row is not recognised, the row is not treated as a block header and a different error is reported.
  • The number of values in a data row must match the number of columns in that block’s header.
  • Empty lines between blocks are allowed and ignored. An empty line within a block (between the header row and its value rows) ends that block; do not insert blank lines between a block header and its data rows.

Detection

The first non-empty line must be the meta header:

1
meta_version

Files that do not start with the meta_version header are rejected.

Document type

document_type_code is a UN/CEFACT UNCL 1001 code (380, 381, 326, …). 381 and the other codes listed in 6.6 create a credit note; other codes are imported as an invoice.

3. File structure

Each block consists of a header row followed by one or more value rows.

# Block Cardinality Source in the model
1 meta 1 CSV version (not part of the invoice model)
2 document 1 document
3 supplier 1 supplier
4 supplier_ids 0..N supplier.ids[]
5 customer 1 customer
6 delivery 0..1 delivery
7 payee 0..1 payee
8 tax_representative 0..1 tax_representative
9 notes 0..N notes[]
10 additional_documents 0..N additional_documents[]
11 preceding_documents 0..N preceding_documents[]
12 discounts_charges 0..N discounts_charges[]
13 payment_details 0..N payment_details[]
14 taxes 1..N taxes[]
15 totals 1 totals
16 items 1..N items[]
17 items_discounts_charges 0..N items[].discounts_charges[]
18 items_commodity_classifications 0..N items[].commodity_classifications[]
19 items_properties 0..N items[].properties[]

A block is recognised by the first header column matching a known column of that block. Longer block names are preferred, so items_discounts_charges is not mistaken for items.

Child item blocks (17–19) are linked to a line by position: items_discounts_charges_position (and the equivalents in 18 and 19) must equal an items_position value. A reference to a non-existent position is a validation error.

The following model fields are not represented in CSV:

Model field Reason
additional_documents[].content Binary attachments are not transferred via CSV
format Assigned by the system after import

Tax breakdown and document totals are taken from the file as-is. The importer does not compute taxes or totals from line items.

4. CSV specification

Legend for the Type column:

Type Meaning
Alphanum Text
Num Decimal number (2450.00)
Date YYYY-MM-DD
Code Value from a code list in section 6
Sign - (allowance / discount) or + (charge / surcharge)

EN 16931 business terms (BT-xx / BG-xx) are given where a direct mapping exists.

4.1. meta

CSV format version. A file with an unsupported version is rejected.

# Column Type Description Example EN 16931
1* meta_version Alphanum Version of this specification 1.0

Example

1
2
meta_version
1.0

4.2. document

Invoice header: type, dates, currency, payment terms and references.

# Column Type Description Example EN 16931
1* document_number Alphanum Unique invoice number in the seller’s system. No identification scheme. inv2024/1 BT-1
2* document_type_code Code Invoice type. See 6.6. 381 and the other codes listed there create a credit note. 380 BT-3
3* document_issue_date Date Date the invoice was issued 2024-06-06 BT-2
4 document_due_date Date Payment due date 2024-07-06 BT-9
5 document_tax_point_date Date VAT tax point date 2024-06-06 BT-7
6 document_period_start_date Date Start of the invoicing period 2024-06-06 BT-73
7 document_period_end_date Date End of the invoicing period 2024-07-06 BT-74
8 document_period_code Code VAT point date code (UNTDID 2475), if used BT-8
9* document_currency_code Code Invoice currency. See 6.3. EUR BT-5
10 document_tax_currency_code Code Tax accounting currency, if different from BT-5 BT-6
11 document_terms Alphanum Payment terms, including SKONTO / VERZUG constructs. See note below. 30 days net BT-20
12 document_accounting_cost Alphanum Buyer’s accounting cost reference COST-44 BT-19
13 document_customer_reference Alphanum Buyer reference / Leitweg-ID. This is a document field, not a customer field. 12345 BT-10
14 document_order_reference Alphanum Purchase order reference issued by the buyer ref123 BT-13
15 document_contract_reference Alphanum Contract reference ref456 BT-12
16 document_project_reference Alphanum Project reference ref789 BT-11
17 document_sales_order_reference Alphanum Sales order reference issued by the seller 123 BT-14
18 document_award_reference Alphanum Tender or lot reference 456 BT-17
19 document_despatch_advice_reference Alphanum Despatch advice reference DA20240606-001 BT-16
20 document_receipt_advice_reference Alphanum Receiving advice reference RA20240607-002 BT-15

XRechnung — BT-1 Invoice number. A unique identifier of the invoice that identifies it in the seller’s system. No Identification Scheme is to be used.

XRechnung — BT-10 Buyer reference / Leitweg-ID. An identifier assigned by the buyer and used for internal routing. As part of the eRechnung steering project, the Leitweg-ID was developed as a routing identifier; its mandatory use is prescribed by the federal government and several German states. States and municipalities that specify alternative routing patterns may use those instead of the Leitweg-ID. For B2B, custom buyer references may be used.

XRechnung — BT-20 Payment terms (SKONTO / VERZUG). Unstructured text must not contain #. Cash discount or late-payment details:

1
2
3
#SKONTO#TAGE=14#PROZENT=2.25#
#SKONTO#TAGE=28#PROZENT=1.00#
#SKONTO#TAGE=14#PROZENT=2.25#BASISBETRAG=357.93#

Each entry starts with #, segments are separated by #, a line ends with #. Keywords must be uppercase. No extra whitespace. A line break must follow a complete SKONTO / VERZUG statement.

Example

1
2
document_number;document_type_code;document_issue_date;document_due_date;document_tax_point_date;document_period_start_date;document_period_end_date;document_period_code;document_currency_code;document_tax_currency_code;document_terms;document_accounting_cost;document_customer_reference;document_order_reference;document_contract_reference;document_project_reference;document_sales_order_reference;document_award_reference;document_despatch_advice_reference;document_receipt_advice_reference
inv2024/1;380;2024-06-06;2024-07-06;;2024-06-06;2024-07-06;;EUR;;30 days net;;12345;ref123;ref456;ref789;123;456;;

4.3. supplier

Seller (your company).

# Column Type Description Example EN 16931
1* supplier_name Alphanum Registered name of the seller Webware internet solutions GmbH BT-27
2 supplier_description Alphanum Additional seller description IT services
3 supplier_trading_name Alphanum Trading name, if different from BT-27 Webware BT-28
4 supplier_vat_id Alphanum Seller VAT identifier DE279247134 BT-31
5 supplier_tax_id_value Alphanum Seller tax registration identifier (e.g. German Steuernummer) 262/481/0918 BT-32
6 supplier_tax_id_scheme Code Scheme of BT-32 FC BT-32-1
7 supplier_endpoint_id_value Alphanum Electronic address (Peppol participant ID value) 279247134 BT-34
8 supplier_endpoint_id_scheme Code Electronic address scheme. See 6.8. 9930 BT-34-1
9 supplier_legal_registration_id_value Alphanum Legal registration identifier HRB12345 BT-30
10 supplier_legal_registration_id_scheme Code Scheme of BT-30 0209 BT-30-1
11 supplier_contact_name Alphanum Contact person or department Max Mustermann BT-41
12 supplier_contact_phone Alphanum Contact phone +49561111111 BT-42
13 supplier_contact_email Alphanum Contact email max@webware24.de BT-43
14 supplier_address_line_1 Alphanum Street and house number, or “Postfach” plus number Teichstr. 14-16 BT-35
15 supplier_address_line_2 Alphanum Additional address line Building A BT-36
16 supplier_address_line_3 Alphanum Third address line BT-162
17 supplier_city Alphanum City Kassel BT-37
18 supplier_zip Alphanum Postal code 34130 BT-38
19 supplier_sub_country Alphanum Country subdivision (Land, region, province) Hessen BT-39
20 supplier_country Code Country. See 6.2. DE BT-40

XRechnung — BT-27 Seller name. The full name under which the seller is registered in the national register of legal entities or as a taxable person, or otherwise trades as a person (or persons) (company name).

XRechnung — BT-31 Seller VAT identifier. The seller’s VAT identification number. If the seller has one, it must be stated here unless Seller Tax Representative Party (BG-11) details are provided.

XRechnung — BT-32 Seller tax registration identifier. A local tax identifier of the seller, or a reference to their registered tax status.

Several seller identifiers (BT-29) are provided in the separate [supplier_ids](#44-supplier_ids) block. Bank account data lives in [payment_details](#413-payment_details), not on the supplier.

Example

1
2
supplier_name;supplier_description;supplier_trading_name;supplier_vat_id;supplier_tax_id_value;supplier_tax_id_scheme;supplier_endpoint_id_value;supplier_endpoint_id_scheme;supplier_legal_registration_id_value;supplier_legal_registration_id_scheme;supplier_contact_name;supplier_contact_phone;supplier_contact_email;supplier_address_line_1;supplier_address_line_2;supplier_address_line_3;supplier_city;supplier_zip;supplier_sub_country;supplier_country
Webware internet solutions GmbH;;;DE279247134;262/481/0918;;279247134;9930;;;;;;Teichstr. 14-16;Building A;;Kassel;34130;Hessen;DE

4.4. supplier_ids

Additional seller identifiers (BG-4 / BT-29). Repeatable. Omit the block if not used.

# Column Type Description Example EN 16931
1 supplier_ids_value Alphanum Identifier value 4012345000001 BT-29
2 supplier_ids_scheme Code Identification scheme (ISO 6523 ICD) 0088 BT-29-1

This is intentionally not mirrored on the buyer: the buyer has a single identifier (customer_id_*, BT-46).

Example

1
2
3
supplier_ids_value;supplier_ids_scheme
4012345000001;0088
123456789;0060

4.5. customer

Buyer.

# Column Type Description Example EN 16931
1 customer_id_value Alphanum Buyer identifier 991-12345-67 BT-46
2 customer_id_scheme Code Scheme of BT-46 0204 BT-46-1
3* customer_name Alphanum Buyer name Webware internet solutions GmbH BT-44
4 customer_description Alphanum Additional buyer description Buyer
5 customer_trading_name Alphanum Buyer trading name Webware Buyer BT-45
6 customer_vat_id Alphanum Buyer VAT identifier DE279247134 BT-48
7 customer_tax_id_value Alphanum Buyer tax registration identifier 262/481/0918
8 customer_tax_id_scheme Code Scheme of the tax identifier FC
9 customer_endpoint_id_value Alphanum Electronic address 279247134 BT-49
10 customer_endpoint_id_scheme Code Electronic address scheme. See 6.8. 9930 BT-49-1
11 customer_legal_registration_id_value Alphanum Legal registration identifier HRB54321 BT-47
12 customer_legal_registration_id_scheme Code Scheme of BT-47 0209 BT-47-1
13 customer_contact_name Alphanum Contact person or department Contact Person BT-56
14 customer_contact_phone Alphanum Contact phone +123456 BT-57
15 customer_contact_email Alphanum Contact email cp@webware24.de BT-58
16 customer_address_line_1 Alphanum Street and house number Teichstr. 14-16 BT-50
17 customer_address_line_2 Alphanum Additional address line Building A BT-51
18 customer_address_line_3 Alphanum Third address line BT-163
19 customer_city Alphanum City Kassel BT-52
20 customer_zip Alphanum Postal code 34130 BT-53
21 customer_sub_country Alphanum Country subdivision Hessen BT-54
22 customer_country Code Country. See 6.2. DE BT-55

XRechnung — BT-44 Buyer name. The full name of the buyer.

Leitweg-ID belongs in document_customer_reference (BT-10), not here.

Example

1
2
customer_id_value;customer_id_scheme;customer_name;customer_description;customer_trading_name;customer_vat_id;customer_tax_id_value;customer_tax_id_scheme;customer_endpoint_id_value;customer_endpoint_id_scheme;customer_legal_registration_id_value;customer_legal_registration_id_scheme;customer_contact_name;customer_contact_phone;customer_contact_email;customer_address_line_1;customer_address_line_2;customer_address_line_3;customer_city;customer_zip;customer_sub_country;customer_country
;;Webware internet solutions GmbH;;;DE279247134;;;;;;;Contact Person;+123456;cp@webware24.de;Teichstr. 14-16;Building A;;Kassel;34130;Hessen;DE

4.6. delivery

Optional deliver-to party and actual delivery date (BG-13). Required by some tax categories (e.g. intra-community supply, code K).

# Column Type Description Example EN 16931
1 delivery_id_value Alphanum Deliver-to location identifier 4031241000006 BT-71
2 delivery_id_scheme Code Scheme of BT-71 0088 BT-71-1
3 delivery_name Alphanum Name of the party to whom the goods / services are delivered, if different from the buyer Webware Warehouse BT-70
4 delivery_date Date Actual delivery / service date 2024-06-15 BT-72
5 delivery_address_line_1 Alphanum Street Teichstr. 14-16 BT-75
6 delivery_address_line_2 Alphanum Additional address line Building B BT-76
7 delivery_address_line_3 Alphanum Third address line BT-165
8 delivery_city Alphanum City Kassel BT-77
9 delivery_zip Alphanum Postal code 34130 BT-78
10 delivery_sub_country Alphanum Country subdivision Hessen BT-79
11 delivery_country Code Country DE BT-80

If a delivery address is provided, postal code and country are typically mandatory in the target format.

Example

1
2
delivery_id_value;delivery_id_scheme;delivery_name;delivery_date;delivery_address_line_1;delivery_address_line_2;delivery_address_line_3;delivery_city;delivery_zip;delivery_sub_country;delivery_country
4031241000006;0088;Webware Warehouse;2024-06-15;Teichstr. 14-16;Building B;;Kassel;34130;Hessen;DE

4.7. payee

Optional payee, when payment is not made to the seller (BG-10).

# Column Type Description Example EN 16931
1 payee_id_value Alphanum Payee identifier 4012345000001 BT-60
2 payee_id_scheme Code Scheme of BT-60 0088 BT-60-1
3 payee_name Alphanum Payee name. Mandatory in EN 16931 when BG-10 is present. Webware internet solutions GmbH BT-59
4 payee_legal_registration_id_value Alphanum Legal registration identifier HRB12345 BT-61
5 payee_legal_registration_id_scheme Code Scheme of BT-61 0209 BT-61-1

Example

1
2
payee_id_value;payee_id_scheme;payee_name;payee_legal_registration_id_value;payee_legal_registration_id_scheme
4012345000001;0088;Webware internet solutions GmbH;HRB12345;0209

4.8. tax_representative

Optional seller tax representative (BG-11).

# Column Type Description Example EN 16931
1 tax_representative_name Alphanum Tax representative name Tax Advisory Services GmbH BT-62
2 tax_representative_vat_id Alphanum VAT identifier DE111111111 BT-63
3 tax_representative_tax_id_value Alphanum Tax registration identifier 111/111/11111
4 tax_representative_tax_id_scheme Code Scheme of the tax identifier FC
5 tax_representative_address_line_1 Alphanum Street Musterstr. 1 BT-64
6 tax_representative_address_line_2 Alphanum Additional address line BT-65
7 tax_representative_address_line_3 Alphanum Third address line BT-164
8 tax_representative_city Alphanum City Berlin BT-66
9 tax_representative_zip Alphanum Postal code 10115 BT-67
10 tax_representative_sub_country Alphanum Country subdivision Berlin BT-68
11 tax_representative_country Code Country DE BT-69

When this block is present, EN 16931 typically requires name, VAT identifier and country.

Example

1
2
tax_representative_name;tax_representative_vat_id;tax_representative_tax_id_value;tax_representative_tax_id_scheme;tax_representative_address_line_1;tax_representative_address_line_2;tax_representative_address_line_3;tax_representative_city;tax_representative_zip;tax_representative_sub_country;tax_representative_country
Tax Advisory Services GmbH;DE111111111;111/111/11111;FC;Musterstr. 1;;;Berlin;10115;Berlin;DE

4.9. notes

Unstructured invoice notes (BG-1). Repeatable.

# Column Type Description Example EN 16931
1 notes_text Alphanum Note text. May include the retention notice per § 14 Abs. 4 Nr. 9 UStG. Payment within 30 days. BT-22
2 notes_subject_code Code Note subject code (UNTDID 4451) PMT BT-21

Example

1
2
3
notes_text;notes_subject_code
Payment within 30 days.;PMT
The delivery date equals the invoice date.;AAC

4.10. additional_documents

Supporting documents and object references (BG-24 / BT-18). Repeatable.

Binary content (content) is not accepted. Provide an external URI instead.

# Column Type Description Example EN 16931
1 additional_documents_id_value Alphanum Document or object identifier ATT-1 BT-122 / BT-18
2 additional_documents_id_scheme Code Identification scheme
3 additional_documents_type_code Code Document type (UNTDID 1001), e.g. 130 invoice 130
4 additional_documents_uri Alphanum External location https://example.com/hours.csv BT-124
5 additional_documents_description Alphanum Description Time list BT-123
6 additional_documents_filename Alphanum File name, if applicable Hours-spent.csv BT-125
7 additional_documents_mime_code Alphanum MIME type text/csv

Object identifier (BT-18, e.g. meter number, phone number, licence plate) is expressed as a row in this block.

Example

1
2
3
additional_documents_id_value;additional_documents_id_scheme;additional_documents_type_code;additional_documents_uri;additional_documents_description;additional_documents_filename;additional_documents_mime_code
ATT-1;;130;https://example.com/hours.csv;Time list;Hours-spent.csv;text/csv
OBJ-2024-1;;130;https://example.com/object;Object reference;;

4.11. preceding_documents

Preceding invoice reference (BG-3). Required for credit notes and corrective invoices. Repeatable.

# Column Type Description Example EN 16931
1 preceding_documents_number Alphanum Preceding invoice number INV20240115-001 BT-25
2 preceding_documents_issue_date Date Issue date of the preceding invoice 2024-01-15 BT-26

Example

1
2
preceding_documents_number;preceding_documents_issue_date
INV20240115-001;2024-01-15

4.12. discounts_charges

Document-level allowances and charges (BG-20 / BG-21). Repeatable.

# Column Type Description Example EN 16931
1 discounts_charges_sign Sign - = allowance (BG-20), + = charge (BG-21) -
2 discounts_charges_base_amount Num Base amount 6000.00 BT-93 / BT-100
3 discounts_charges_percent Num Percentage 1.67 BT-94 / BT-101
4 discounts_charges_amount Num Amount excluding VAT 100.00 BT-92 / BT-99
5 discounts_charges_tax_code Code VAT category. See 6.5. S BT-95 / BT-102
6 discounts_charges_tax_scheme Alphanum Tax scheme, typically VAT VAT
7 discounts_charges_tax_percent Num VAT rate 19.00 BT-96 / BT-103
8 discounts_charges_reason Alphanum Reason in text Early payment BT-97 / BT-104
9 discounts_charges_reason_code Code Reason code (UNTDID 5189 / 7161) 95 BT-98 / BT-105

Example

1
2
3
discounts_charges_sign;discounts_charges_base_amount;discounts_charges_percent;discounts_charges_amount;discounts_charges_tax_code;discounts_charges_tax_scheme;discounts_charges_tax_percent;discounts_charges_reason;discounts_charges_reason_code
-;6000.00;1.67;100.00;S;VAT;19.00;Early payment;95
+;6000.00;;100.00;S;VAT;19.00;Insurance;FC

4.13. payment_details

Payment means and account data (BG-16). Repeatable — several accounts may be given.

# Column Type Description Example EN 16931
1 payment_details_method_code Code Payment means code. See 6.1. 58 BT-81
2 payment_details_method_name Alphanum Payment means text SEPA credit transfer BT-82
3 payment_details_iban Alphanum IBAN (or account identifier outside SEPA) DE50520501511004485469 BT-84
4 payment_details_bic Alphanum BIC. Required for non-SEPA credit transfers (30) and for some SEPA countries (e.g. CH, SM, MC). Not required for SEPA SCT (58). WELADED1SIE BT-86
5 payment_details_account_name Alphanum Account name Webware GmbH Payment Account BT-85
6 payment_details_remittance_information Alphanum Remittance information (payment reference) inv2024/1 BT-83
7 payment_details_card_number Alphanum Payment card primary account number (masked) BT-87
8 payment_details_card_holder_name Alphanum Card holder name BT-88
9 payment_details_card_network Alphanum Card network
10 payment_details_direct_debit_mandate_id Alphanum Direct debit mandate reference BT-89
11 payment_details_direct_debit_payer_account Alphanum Debited account identifier BT-91

XRechnung — BT-84 / BT-86. For SEPA credit transfers (code 58), the IBAN is sufficient. For transfers outside the SEPA area (code 30), the BIC is required. Exceptions within SEPA where the BIC is still mandatory: San Marino, Monaco, Switzerland, Saint-Pierre and Miquelon.

Example

1
2
payment_details_method_code;payment_details_method_name;payment_details_iban;payment_details_bic;payment_details_account_name;payment_details_remittance_information;payment_details_card_number;payment_details_card_holder_name;payment_details_card_network;payment_details_direct_debit_mandate_id;payment_details_direct_debit_payer_account
58;SEPA credit transfer;DE50520501511004485469;WELADED1SIE;Webware GmbH Payment Account;inv2024/1;;;;;

4.14. taxes

VAT breakdown (BG-23). At least one row is required. Values are not calculated from invoice lines.

# Column Type Description Example EN 16931
1 taxes_taxable_amount Num Taxable amount for this category 6000.00 BT-116
2 taxes_currency_code Code Currency of the tax amount, if needed EUR
3 taxes_amount Num VAT amount for this category 1140.00 BT-117
4 taxes_percent Num VAT rate. Use 0 when the category is outside the scope of VAT. 19.00 BT-119
5 taxes_code Code VAT category. See 6.5. S BT-118
6 taxes_scheme Alphanum Tax scheme, typically VAT VAT
7 taxes_exemption_reason Alphanum Exemption reason text. For category AE: “Umkehrung der Steuerschuldnerschaft” (or the equivalent in the invoice language). BT-120
8 taxes_exemption_reason_code Code VATEX code VATEX-EU-IC BT-121

taxes_amount should equal taxes_taxable_amount × taxes_percent / 100 for the category (subject to rounding rules of the target format).

Example

1
2
taxes_taxable_amount;taxes_currency_code;taxes_amount;taxes_percent;taxes_code;taxes_scheme;taxes_exemption_reason;taxes_exemption_reason_code
6000.00;EUR;1140.00;19.00;S;VAT;;

4.15. totals

Document totals (BG-22). All figures come from the file. The importer checks consistency (section 5) and does not recalculate.

# Column Type Description Example EN 16931
1* totals_item_subtotal Num Sum of invoice line net amounts 6000.00 BT-106
2* totals_subtotal Num Invoice total without VAT 6000.00 BT-109
3* totals_total Num Invoice total with VAT 7140.00 BT-112
4 totals_discount Num Sum of allowances on document level 100.00 BT-107
5 totals_charge Num Sum of charges on document level 100.00 BT-108
6 totals_paid Num Paid amount already received BT-113
7 totals_round Num Rounding amount BT-114
8* totals_payable Num Amount due for payment 7140.00 BT-115
9 totals_tax_total Num Invoice total VAT amount in invoice currency 1140.00 BT-110
10 totals_tax_total_alt_currency Num Invoice total VAT amount in accounting currency BT-111

XRechnung — BT-115 Amount due for payment. The outstanding amount: BT-112 minus BT-113. For a fully paid invoice, this amount is zero. The amount is negative if BT-113 is greater than BT-112.

Example

1
2
totals_item_subtotal;totals_subtotal;totals_total;totals_discount;totals_charge;totals_paid;totals_round;totals_payable;totals_tax_total;totals_tax_total_alt_currency
6000.00;6000.00;7140.00;;;;;7140.00;1140.00;

4.16. items

Invoice lines (BG-25). At least one row is required.

# Column Type Description Example EN 16931
1* items_position Alphanum Unique line identifier. Used as the key for child blocks. Each position must be unique in the file; the parser does not enforce uniqueness — if duplicate positions appear, child block rows are linked to every line with that position. 1 BT-126
2 items_name Alphanum Item name. Required by EN 16931. Onboarding BT-153
3 items_description Alphanum Item description Kickoff package BT-154
4 items_note Alphanum Invoice line note Includes setup BT-127
5* items_quantity Num Invoiced quantity 10.00 BT-129
6* items_unit_code Code Unit of measure for BT-129. See 6.4. C62 BT-130
7 items_price Num Item net price (after item price discount) 200.00 BT-146
8 items_price_quantity Num Item price base quantity 1 BT-149
9 items_price_unit_code Code Unit of the price base quantity C62 BT-150
10 items_price_discount_charge_sign Sign Sign of the item price allowance/charge -
11 items_price_discount_charge_base_amount Num Item gross price (before price discount) 220.00 BT-148
12 items_price_discount_charge_amount Num Item price discount 20.00 BT-147
13* items_subtotal Num Invoice line net amount 2000.00 BT-131
14 items_tax_percent Num Invoiced item VAT rate 19.00 BT-152
15* items_tax_code Code Invoiced item VAT category. See 6.5. S BT-151
16* items_tax_scheme Alphanum Tax scheme, typically VAT VAT
17 items_supplier_item_id Alphanum Seller’s item identifier onb.2024.6 BT-155
18 items_customer_item_id Alphanum Buyer’s item identifier BUY-ONB BT-156
19 items_standard_item_id_value Alphanum Standard item identifier (e.g. GTIN) 12345678 BT-157
20 items_standard_item_id_scheme Code Scheme of BT-157 0160 BT-157-1
21 items_order_position_reference Alphanum Referenced purchase order line 1 BT-132
22 items_document_reference_id_value Alphanum Invoice line object identifier PO-2024-1 BT-128
23 items_document_reference_id_scheme Code Scheme of BT-128
24 items_document_reference_type_code Code Document type code 130
25 items_accounting_cost Alphanum Invoice line Buyer accounting reference 1287:65464 BT-133
26 items_period_start_date Date Invoice line period start 2024-06-06 BT-134
27 items_period_end_date Date Invoice line period end 2024-06-30 BT-135
28 items_origin_country Code Item country of origin DE BT-159

XRechnung — BT-126 Invoice line identifier. A unique identifier for the invoice line in question.

XRechnung — BT-146 Item net price. The price of an item excluding VAT, after deducting the discount applicable to this invoice line. BT-146 must equal BT-148 minus BT-147.

XRechnung — BT-131 Invoice line net amount. The total amount of the invoice line excluding VAT, including all allowances and charges applicable to the line.

Line-level VAT amount and line gross amount (item_tax_total / item_total) are not in this format. VAT is stated in the taxes block. Several allowances/charges per line go in [items_discounts_charges](#417-items_discounts_charges).

Example

1
2
3
items_position;items_name;items_description;items_note;items_quantity;items_unit_code;items_price;items_price_quantity;items_price_unit_code;items_price_discount_charge_sign;items_price_discount_charge_base_amount;items_price_discount_charge_amount;items_subtotal;items_tax_percent;items_tax_code;items_tax_scheme;items_supplier_item_id;items_customer_item_id;items_standard_item_id_value;items_standard_item_id_scheme;items_order_position_reference;items_document_reference_id_value;items_document_reference_id_scheme;items_document_reference_type_code;items_accounting_cost;items_period_start_date;items_period_end_date;items_origin_country
1;Onboarding;;;10.00;C62;200.00;1;C62;;;;2000.00;19.00;S;VAT;onb.2024.6;;;;;;;;;;;
2;Support;June 2024;;20.00;C62;200.00;1;C62;;;;4000.00;19.00;S;VAT;sup.2024;;;;;;;;;;;

4.17. items_discounts_charges

Line-level allowances and charges (BG-27 / BG-28). Repeatable. Several rows may refer to the same items_position.

# Column Type Description Example EN 16931
1* items_discounts_charges_position Alphanum Must match items_position 1
2* items_discounts_charges_sign Sign - = allowance (BG-27), + = charge (BG-28) -
3 items_discounts_charges_base_amount Num Base amount 2000.00 BT-137 / BT-142
4 items_discounts_charges_percent Num Percentage 2.50 BT-138 / BT-143
5* items_discounts_charges_amount Num Amount excluding VAT 50.00 BT-136 / BT-141
6 items_discounts_charges_reason Alphanum Reason in text Volume discount BT-139 / BT-144
7 items_discounts_charges_reason_code Code Reason code 95 BT-140 / BT-145

Example

1
2
3
items_discounts_charges_position;items_discounts_charges_sign;items_discounts_charges_base_amount;items_discounts_charges_percent;items_discounts_charges_amount;items_discounts_charges_reason;items_discounts_charges_reason_code
1;-;2000.00;2.50;50.00;Volume discount;95
1;+;2000.00;;50.00;Handling surcharge;

4.18. items_commodity_classifications

Item classification identifiers (BT-158). Repeatable.

# Column Type Description Example EN 16931
1* items_commodity_classifications_position Alphanum Must match items_position 1
2 items_commodity_classifications_code Alphanum Classification code 12344321 BT-158
3 items_commodity_classifications_scheme Code Identification scheme STI BT-158-1
4 items_commodity_classifications_scheme_version Alphanum Scheme version 0.1 BT-158-2

Example

1
2
3
items_commodity_classifications_position;items_commodity_classifications_code;items_commodity_classifications_scheme;items_commodity_classifications_scheme_version
1;12344321;STI;0.1
2;65434568;STI;0.1

4.19. items_properties

Item attributes (BG-32). Repeatable.

# Column Type Description Example EN 16931
1* items_properties_position Alphanum Must match items_position 1
2 items_properties_name Alphanum Attribute name Contract BT-160
3 items_properties_value Alphanum Attribute value ONB-2024 BT-161

Example

1
2
3
items_properties_position;items_properties_name;items_properties_value
1;Contract;ONB-2024
2;Period;June 2024

5. Totals consistency

The importer verifies the figures supplied in the file. No value is substituted or recomputed. A mismatch is returned as a validation error that includes both amounts.

Checked identities:

Check Formula
Line net vs item subtotal Σ items_subtotal = totals_item_subtotal
VAT breakdown vs tax total Σ taxes_amount = totals_tax_total (empty tax total is treated as 0)
Net + VAT vs gross totals_subtotal + totals_tax_total = totals_total
Gross − prepaid vs payable totals_total − totals_paid = totals_payable (empty paid is treated as 0)

totals_discount and totals_charge are stored as provided; they are not currently cross-checked against discounts_charges.

6. Code lists

6.1. Payment means code (UNCL4461)

Common codes:

Code Name
1 Instrument not defined
10 In cash
30 Credit transfer
31 Debit transfer
42 Payment to bank account
48 Bank card
49 Direct debit
58 SEPA credit transfer
59 SEPA direct debit

Full list: https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4461/

6.2. ISO 3166-1 Alpha-2 country codes

Two-letter country codes. Germany is DE.

Full list: https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO3166/

6.3. ISO 4217 currency codes

Invoices in euro use EUR.

Full list: https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO4217/

6.4. Unit codes

UNECE Recommendation 20 (and Rec. 21 for some packaging units). Common values:

Code Name
C62 One (unit)
H87 Piece
DAY Day
HUR Hour
MON Month
KGM Kilogram
LTR Litre
MTR Metre

Full lists:

6.5. Tax category codes

Subset of UNCL 5305 used in EN 16931:

Code Name Description
S Standard rate Standard VAT rate
Z Zero rated goods Goods at a zero rate
E Exempt from tax Taxes are not applicable
AE VAT reverse charge Standard VAT rate is levied from the invoicee
G Free export item, VAT not charged Free export, taxes not charged
O Services outside scope of tax Taxes not applicable to the services
K VAT exempt for EEA intra-community supply Intra-community supply in the EEA
L Canary Islands general indirect tax IGIC
M Tax for production, services and importation in Ceuta and Melilla IPSI

Full list: https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5305/

Exemption reason codes (VATEX): https://docs.peppol.eu/poacc/billing/3.0/codelist/vatex/

6.6. Invoice types

UNCL 1001 codes used directly in document_type_code:

Code Name German name
380 Commercial invoice Rechnung
381 Credit note Gutschrift
326 Partial invoice Teilrechnung
384 Corrected invoice Rechnungskorrektur
389 Self-billed invoice Self-Billing
875 Partial construction invoice Abschlagsrechnung
876 Partial final construction invoice Teilschlussrechnung
877 Final construction invoice Schlussrechnung

381 is the most common credit note code. The following UNCL 1001 codes are also imported as an xTool credit note (EN 16931 BR-CL-01): 81, 83, 261, 262, 296, 308, 381, 396, 420, 458, 532. Any other code, including the other invoice types listed above, is imported as an invoice.

6.7. Identifier schemes (ISO 6523 ICD)

Used in *_id_scheme / *_ids_scheme columns (not EAS). Common values:

Code Description
0088 EAN Location Code (GLN)
0060 DUNS Number
0160 GTIN
0209 GS1 Company Prefix / LEI-related legal registration (context-dependent)
FC Tax number (often used for BT-32)

ICD list: https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/

6.8. Electronic Address Scheme (EAS)

Used in supplier_endpoint_id_scheme and customer_endpoint_id_scheme.

Code Description
0204 Leitweg-ID
9930 Germany VAT number
9925 Belgium VAT number
9934 Croatia VAT number
9938 Luxembourg VAT number
0088 EAN Location Code

Peppol participant IDs have the form <EAS>:<value>, e.g. 9930:DE279247134 or 0204:999-123456-555. In CSV the scheme and value are separate columns.

Full list: https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/

7. Complete examples

7.1. Minimal invoice

Required blocks only: meta, document, supplier, customer, taxes, totals, items.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
meta_version
1.0
document_number;document_type_code;document_issue_date;document_due_date;document_tax_point_date;document_period_start_date;document_period_end_date;document_period_code;document_currency_code;document_tax_currency_code;document_terms;document_accounting_cost;document_customer_reference;document_order_reference;document_contract_reference;document_project_reference;document_sales_order_reference;document_award_reference;document_despatch_advice_reference;document_receipt_advice_reference
inv2024/1;380;2024-06-06;2024-07-06;;2024-06-06;2024-07-06;;EUR;;30 days net;;12345;ref123;ref456;ref789;123;456;;
supplier_name;supplier_description;supplier_trading_name;supplier_vat_id;supplier_tax_id_value;supplier_tax_id_scheme;supplier_endpoint_id_value;supplier_endpoint_id_scheme;supplier_legal_registration_id_value;supplier_legal_registration_id_scheme;supplier_contact_name;supplier_contact_phone;supplier_contact_email;supplier_address_line_1;supplier_address_line_2;supplier_address_line_3;supplier_city;supplier_zip;supplier_sub_country;supplier_country
Webware internet solutions GmbH;;;DE279247134;262/481/0918;;279247134;9930;;;;;;Teichstr. 14-16;Building A;;Kassel;34130;Hessen;DE
customer_id_value;customer_id_scheme;customer_name;customer_description;customer_trading_name;customer_vat_id;customer_tax_id_value;customer_tax_id_scheme;customer_endpoint_id_value;customer_endpoint_id_scheme;customer_legal_registration_id_value;customer_legal_registration_id_scheme;customer_contact_name;customer_contact_phone;customer_contact_email;customer_address_line_1;customer_address_line_2;customer_address_line_3;customer_city;customer_zip;customer_sub_country;customer_country
;;Webware internet solutions GmbH;;;DE279247134;;;;;;;Contact Person;+123456;cp@webware24.de;Teichstr. 14-16;Building A;;Kassel;34130;Hessen;DE
taxes_taxable_amount;taxes_currency_code;taxes_amount;taxes_percent;taxes_code;taxes_scheme;taxes_exemption_reason;taxes_exemption_reason_code
6000.00;EUR;1140.00;19.00;S;VAT;;
totals_item_subtotal;totals_subtotal;totals_total;totals_discount;totals_charge;totals_paid;totals_round;totals_payable;totals_tax_total;totals_tax_total_alt_currency
6000.00;6000.00;7140.00;;;;;7140.00;1140.00;
items_position;items_name;items_description;items_note;items_quantity;items_unit_code;items_price;items_price_quantity;items_price_unit_code;items_price_discount_charge_sign;items_price_discount_charge_base_amount;items_price_discount_charge_amount;items_subtotal;items_tax_percent;items_tax_code;items_tax_scheme;items_supplier_item_id;items_customer_item_id;items_standard_item_id_value;items_standard_item_id_scheme;items_order_position_reference;items_document_reference_id_value;items_document_reference_id_scheme;items_document_reference_type_code;items_accounting_cost;items_period_start_date;items_period_end_date;items_origin_country
1;Onboarding;;;10.00;C62;200.00;1;C62;;;;2000.00;19.00;S;VAT;onb.2024.6;;;;;;;;;;;
2;Support;June 2024;;20.00;C62;200.00;1;C62;;;;4000.00;19.00;S;VAT;sup.2024;;;;;;;;;;;

7.2. Peppol-oriented invoice

Endpoint IDs on both parties plus SEPA payment details. Same required blocks as 7.1, with payment_details added.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
meta_version
1.0
document_number;document_type_code;document_issue_date;document_due_date;document_tax_point_date;document_period_start_date;document_period_end_date;document_period_code;document_currency_code;document_tax_currency_code;document_terms;document_accounting_cost;document_customer_reference;document_order_reference;document_contract_reference;document_project_reference;document_sales_order_reference;document_award_reference;document_despatch_advice_reference;document_receipt_advice_reference
inv2024/peppol-1;380;2024-06-06;2024-07-06;;2024-06-06;2024-07-06;;EUR;;30 days net;;12345;PO-2024-1;;;;;;
supplier_name;supplier_description;supplier_trading_name;supplier_vat_id;supplier_tax_id_value;supplier_tax_id_scheme;supplier_endpoint_id_value;supplier_endpoint_id_scheme;supplier_legal_registration_id_value;supplier_legal_registration_id_scheme;supplier_contact_name;supplier_contact_phone;supplier_contact_email;supplier_address_line_1;supplier_address_line_2;supplier_address_line_3;supplier_city;supplier_zip;supplier_sub_country;supplier_country
Webware internet solutions GmbH;;;DE279247134;;;279247134;9930;;;Max Mustermann;+49561111111;max@webware24.de;Teichstr. 14-16;;;Kassel;34130;Hessen;DE
customer_id_value;customer_id_scheme;customer_name;customer_description;customer_trading_name;customer_vat_id;customer_tax_id_value;customer_tax_id_scheme;customer_endpoint_id_value;customer_endpoint_id_scheme;customer_legal_registration_id_value;customer_legal_registration_id_scheme;customer_contact_name;customer_contact_phone;customer_contact_email;customer_address_line_1;customer_address_line_2;customer_address_line_3;customer_city;customer_zip;customer_sub_country;customer_country
;;Buyer GmbH;;;DE111111111;;;111111111;9930;;;Lisa Johnson;+49301111111;lj@buyer.de;Hauptstr. 1;;;Berlin;10115;Berlin;DE
payment_details_method_code;payment_details_method_name;payment_details_iban;payment_details_bic;payment_details_account_name;payment_details_remittance_information;payment_details_card_number;payment_details_card_holder_name;payment_details_card_network;payment_details_direct_debit_mandate_id;payment_details_direct_debit_payer_account
58;SEPA credit transfer;DE89370400440532013000;COBADEFFXXX;Webware internet solutions GmbH;inv2024/peppol-1;;;;;
taxes_taxable_amount;taxes_currency_code;taxes_amount;taxes_percent;taxes_code;taxes_scheme;taxes_exemption_reason;taxes_exemption_reason_code
6000.00;EUR;1140.00;19.00;S;VAT;;
totals_item_subtotal;totals_subtotal;totals_total;totals_discount;totals_charge;totals_paid;totals_round;totals_payable;totals_tax_total;totals_tax_total_alt_currency
6000.00;6000.00;7140.00;;;;;7140.00;1140.00;
items_position;items_name;items_description;items_note;items_quantity;items_unit_code;items_price;items_price_quantity;items_price_unit_code;items_price_discount_charge_sign;items_price_discount_charge_base_amount;items_price_discount_charge_amount;items_subtotal;items_tax_percent;items_tax_code;items_tax_scheme;items_supplier_item_id;items_customer_item_id;items_standard_item_id_value;items_standard_item_id_scheme;items_order_position_reference;items_document_reference_id_value;items_document_reference_id_scheme;items_document_reference_type_code;items_accounting_cost;items_period_start_date;items_period_end_date;items_origin_country
1;Onboarding;;;10.00;C62;200.00;1;C62;;;;2000.00;19.00;S;VAT;onb.2024.6;;;;;;;;;;;
2;Support;June 2024;;20.00;C62;200.00;1;C62;;;;4000.00;19.00;S;VAT;sup.2024;;;;;;;;;;;

For questions about CSV import or this specification, see Support.