Peppol UBL e-invoice

Invoice data from your ERP, as a Peppol UBL file

Generate Peppol e-invoices from your ERP

Since 1 January 2026, Belgian companies liable to VAT must send each other structured electronic invoices, by default over the Peppol network. In Germany, companies must be able to receive e-invoices from other German companies since 1 January 2025, and must issue them from 1 January 2027 when their turnover of the previous year exceeds 800,000 euros (BMF). On Peppol, ERPs and billing systems send Peppol BIS Billing 3.0 invoices: XML files in the UBL 2.1 syntax of the European standard EN 16931. The ERP hands each file to its Peppol access point, which delivers it to the access point of the buyer. Your system sends the invoice to the Carbone API as JSON and gets back the XML for the access point.

In this example, Fabrikam Events NV, in Antwerp, invoices Contoso Pharma GmbH, in Frankfurt, for 4 passes to a conference in Antwerp, 2 seats at a masterclass and a networking dinner. Admission to an event and catering are taxed where they take place (VAT Directive, articles 53 and 55), so the German buyer pays Belgian VAT: 21% on the passes, the masterclass and the drinks, 12% on the food. The generated file passes the UBL 2.1 schema and the official EN 16931 and Peppol BIS Billing 3.0 Schematron rules, without errors or warnings.

In this example, you will:

  • Write the Peppol identifiers and the electronic addresses of the parties
  • Compute the line amounts and the allowance
  • Build the VAT breakdown, one subtotal per VAT rate
  • Compute document totals that pass the EN 16931 rules to the cent
  • Remove the optional elements that have no value

Peppol invoice structure

A Peppol invoice follows the order of the UBL schema. The codes in the second column are the business terms (BT) and groups (BG) of EN 16931.

Elements EN 16931 Content
cbc:CustomizationID, cbc:ProfileID BT-24, BT-23 Peppol BIS Billing 3.0 identifiers, fixed in the template
cbc:ID, cbc:IssueDate, cbc:DueDate, cbc:InvoiceTypeCode BT-1, BT-2, BT-9, BT-3 Invoice number, dates, type 380 (commercial invoice)
cbc:BuyerReference, cac:OrderReference BT-10, BT-13 Reference of the buyer and purchase order number: Peppol requires at least one
cac:InvoicePeriod BG-14 Dates of the conference
cac:AccountingSupplierParty, cac:AccountingCustomerParty BG-4, BG-7 Seller and buyer: electronic address, postal address, VAT number, legal name, contact
cac:Delivery BG-13 The venue in Antwerp, where the services take place
cac:PaymentMeans, cac:PaymentTerms BG-16, BT-20 SEPA credit transfer (code 58), IBAN, Belgian structured communication, payment terms
cac:AllowanceCharge BG-20, BG-21 Allowances and charges on the whole invoice, each with its VAT category and rate
cac:TaxTotal BT-110, BG-23 VAT total, and one cac:TaxSubtotal per VAT category and rate
cac:LegalMonetaryTotal BG-22 Document totals
cac:InvoiceLine BG-25 One per line: quantity, net amount, item, VAT category and rate, price

How to generate a Peppol invoice

1. Write the Peppol identifiers and the parties

  • cbc:CustomizationID and cbc:ProfileID are fixed text in the template. urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0 says that the invoice follows EN 16931 with the Peppol rules, and urn:fdc:peppol.eu:2017:poacc:billing:01:1.0 names the billing process.
  • Each party has an electronic address, its Peppol ID: <cbc:EndpointID schemeID="{d.seller.endpointScheme}">{d.seller.endpointId}</cbc:EndpointID>. The scheme comes from the Peppol EAS code list: 0208 for the Belgian enterprise number of the seller, 9930 for the German VAT number of the buyer.
  • cac:PartyLegalEntity repeats the enterprise number of the seller with schemeID="0208", and cbc:CompanyLegalForm holds the legal form and the register that Belgian companies print on their invoices: NV, RPR Antwerpen, afdeling Antwerpen.
  • {d.invoice.issueDate:formatD('YYYY-MM-DD')} writes the dates in the xs:date format. See the XML guide.
  • cbc:PaymentID holds the Belgian structured communication of the transfer, +++260/1842/00140+++.

Validators check the check digits of the identifiers, so the IBAN of this example has valid check digits and a bank code that the National Bank of Belgium lists as free: it belongs to no account. The enterprise number and the VAT numbers are fictional too, with valid check digits.

2. Write the amounts with a dot

EN 16931 amounts have 2 decimals at most, with a dot. The first line of the template sets the options and an alias:

{o.lang=en-us}{o.useHighPrecisionArithmetic=true}{#amount($value) = $value:formatN(2):replace(',', '')}
  • {o.lang=en-us} gives :formatN the dot of English, whatever the lang of the request.
  • The parametrized alias amount removes the thousands separator: {$amount(c.lineTotal)} prints 4994.00.
  • {o.useHighPrecisionArithmetic=true} computes the amounts in decimal arithmetic, exact to the cent.
  • Unit prices can have more decimals: {d.lines[i].price} prints them as they are, like 38.5.

3. Repeat the lines and the allowances

{d.lines[i]} at the start of the line of <cac:InvoiceLine> opens the repeated block, and {d.lines[i+1]} before </Invoice> closes it, as in a TXT template. The generated file keeps its indentation, without an empty line after the last item. {d.allowanceCharges[i]} repeats cac:AllowanceCharge the same way.

The first line of the template also computes the amounts, with :set:

  • {d.lines[].quantity:mul(.price):round(2):set(.net)} adds the net amount to each line: 4 passes at 890 give 3560.00. Peppol rule R120 checks it.
  • {d.allowanceCharges[].baseAmount:mul(.percent):div(100):round(2):set(.amount)} computes the group discount: 10% of 3560.00 gives 356.00, as Peppol rule R040 requires. The ERP sends the percentage and the base amount of each allowance or charge.
  • {d.allowanceCharges[i].chargeIndicator} prints false for an allowance and true for a charge.

4. Build the VAT breakdown

EN 16931 asks for one cac:TaxSubtotal per VAT category and rate. The taxable amount of a rate is the sum of its lines, minus its allowances, plus its charges (rule BR-S-08), and its VAT is rounded to the cent (BR-CO-17). The tags at the end of the <cac:TaxTotal> line compute it:

  • {d.lines[].vatCategory:append(.vatRate):set(.taxKey)} gives each line a key, S21 or S12. The same tag gives a key to each allowance.
  • {d.allowanceCharges[].chargeIndicator:ifEQ(true):show(1):elseShow(-1):mul(.amount):set(.net)} turns the allowance into a negative amount, -356.
  • {d.lines[]:set(c.base[])} and {d.allowanceCharges[]:set(c.base[])} copy the lines and the allowances into one list.
  • {c.base[].net:aggSum(.taxKey):set(.taxable)} adds up the amounts of each key: 3560 + 900 + 154 - 356 gives 4258.00 for S21.
  • {c.base[]:set(c.vat[key=.taxKey])} keeps one item per key in c.vat.
  • {c.vat[].taxable:mul(.vatRate):div(100):round(2):set(.tax)} computes the VAT of each rate, and {c.vat[].tax:aggSum:round(2):set(c.vatTotal)} adds up the rounded amounts, as rule BR-CO-14 checks.

{c.vat[i]} and {c.vat[i+1]} repeat cac:TaxSubtotal for each rate:

  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="EUR">939.78</cbc:TaxAmount>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="EUR">4258.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="EUR">894.18</cbc:TaxAmount>
      <cac:TaxCategory>
        <cbc:ID>S</cbc:ID>
        <cbc:Percent>21</cbc:Percent>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:TaxCategory>
    </cac:TaxSubtotal>
    <cac:TaxSubtotal>
      <cbc:TaxableAmount currencyID="EUR">380.00</cbc:TaxableAmount>
      <cbc:TaxAmount currencyID="EUR">45.60</cbc:TaxAmount>
      ...

Learn more about partitioned aggregators and grouping with :set.

5. Compute the document totals

The tags at the end of the <cac:LegalMonetaryTotal> line compute the totals that EN 16931 rules BR-CO-10 to BR-CO-16 check:

Element Tag Result
cbc:LineExtensionAmount {d.lines[].net:aggSum:round(2):set(c.lineTotal)} 4994.00
cbc:AllowanceTotalAmount {d.allowanceCharges[chargeIndicator=false].amount:aggSum:round(2):set(c.allowanceTotal)} 356.00
cbc:TaxExclusiveAmount {c.lineTotal:sub(c.allowanceTotal):add(c.chargeTotal):set(c.taxExclusive)} 4638.00
cbc:TaxInclusiveAmount {c.taxExclusive:add(c.vatTotal):set(c.taxInclusive)} 5577.78
cbc:PayableAmount {c.taxInclusive:sub(d.invoice.prepaidAmount):set(c.payable)} 5577.78

c.chargeTotal adds up the charges the same way, with [chargeIndicator=true]. See aggregators and math formatters.

6. Remove the optional elements without value

Peppol rejects empty elements (rule R008). Conditional blocks remove the optional elements when their value is missing:

  • {d.invoice.note:ifNEM:showBegin} keeps cbc:Note only when the invoice has a note.
  • {c.chargeTotal:ifGT(0):showBegin} and {d.invoice.prepaidAmount:ifGT(0):showBegin} remove cbc:ChargeTotalAmount and cbc:PrepaidAmount: this invoice has no charge and no prepayment.
  • {d.lines[i].orderLineId:ifNEM:showBegin} keeps cac:OrderLineReference for the 2 lines of the purchase order only.
  • {c.vat[i].exemptionCode:ifNEM:showBegin} adds the exemption reason code of the lines, which the VAT categories E, AE, K and G need.

Write each begin tag at the end of the line above the block, and the end tag at the end of its last line: a removed block leaves no empty line. See XML conditions.

Send the same invoice as an XRechnung

XRechnung is the German core invoice usage specification (CIUS) of EN 16931, as Peppol BIS is the Peppol one, and the standard of the German public sector. To generate an XRechnung 3.0 in UBL, change one line of the template:

  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</cbc:CustomizationID>

The German rules (BR-DE) also require the buyer reference, the contact of the seller with a name, a telephone number and an email address, the city and the post code of both parties, and the payment instructions: the template already writes them. With this line changed, the result of this example passes the EN 16931 rules and the XRechnung 3.0.2 Schematron of KoSIT. For a German public buyer, cbc:BuyerReference holds its Leitweg-ID, and its electronic address on Peppol uses the scheme 0204.

Trusted by 800+ paid customers in 40+ countries

Finance
Healthcare
Insurance
Legal
Public
Retail
Energy
Software
Telecom
Dior
Thales
Younited
Danfoss
CMA CGM
Illumina
KparK
Scalingo
French Ministry of the Armed Forces
BMW
Telus
Bestseller
Flagship Biosciences
Insly
Ninox
Sodexo