Peppol UBL e-invoice
Invoice data from your ERP, as a Peppol UBL file
- Template
- XML
- Export as
- XML
- Carbone
- 5.18+
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:CustomizationIDandcbc:ProfileIDare fixed text in the template.urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0says that the invoice follows EN 16931 with the Peppol rules, andurn:fdc:peppol.eu:2017:poacc:billing:01:1.0names 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:0208for the Belgian enterprise number of the seller,9930for the German VAT number of the buyer. cac:PartyLegalEntityrepeats the enterprise number of the seller withschemeID="0208", andcbc:CompanyLegalFormholds 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 thexs:dateformat. See the XML guide.cbc:PaymentIDholds 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:formatNthe dot of English, whatever thelangof the request.- The parametrized alias
amountremoves the thousands separator:{$amount(c.lineTotal)}prints4994.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, like38.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 give3560.00. Peppol rule R120 checks it.{d.allowanceCharges[].baseAmount:mul(.percent):div(100):round(2):set(.amount)}computes the group discount: 10% of3560.00gives356.00, as Peppol rule R040 requires. The ERP sends the percentage and the base amount of each allowance or charge.{d.allowanceCharges[i].chargeIndicator}printsfalsefor an allowance andtruefor 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,S21orS12. 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 gives4258.00forS21.{c.base[]:set(c.vat[key=.taxKey])}keeps one item per key inc.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}keepscbc:Noteonly when the invoice has a note.{c.chargeTotal:ifGT(0):showBegin}and{d.invoice.prepaidAmount:ifGT(0):showBegin}removecbc:ChargeTotalAmountandcbc:PrepaidAmount: this invoice has no charge and no prepayment.{d.lines[i].orderLineId:ifNEM:showBegin}keepscac:OrderLineReferencefor 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.
Related Examples
Trusted by 800+ paid customers in 40+ countries














