---
source: https://carbone.io/examples/peppol-ubl-e-invoice/
title: "Peppol E-Invoicing Software: UBL XML from JSON | Carbone"
description: "Add Peppol e-invoicing to your ERP or billing software: Carbone turns invoice data into UBL 2.1 XML, VAT breakdown and EN 16931 totals included."
generated_at: "2026-11-17"
---

# Peppol UBL e-invoice

Invoice data from your ERP, as a Peppol UBL file

[![Peppol UBL e-invoice: XML generated from an XML template and JSON data](/examples/peppol-ubl-e-invoice/thumb-result.webp)](/examples/peppol-ubl-e-invoice/result.xml "Download the generated document")

[Download template](/examples/peppol-ubl-e-invoice/template.xml)

[Sample data](/examples/peppol-ubl-e-invoice/data.json)

[Download the generated XML](/examples/peppol-ubl-e-invoice/result.xml)

- **Template:** XML
- **Export as:** XML
- **Carbone:** 5.18+

Features

-   [Loop](/documentation/design/repetitions/with-arrays.md)
-   [Aggregation](/documentation/design/computation/aggregation.md)
-   [Set](/documentation/design/computation/store-and-transform.md)
-   [Condition](/documentation/design/conditions/overview.md)
-   [Alias](/documentation/design/substitutions/aliases.md)
-   [Math](/documentation/design/computation/simple-mathematics.md)

## Generate Peppol e-invoices from your ERP

Since 1 January 2026, Belgian companies liable to VAT must send each other [structured electronic invoices](https://einvoice.belgium.be/en/FAQ/general-questions-b2b), 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](https://www.bundesfinanzministerium.de/Content/DE/FAQ/e-rechnung.html)). 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](https://eur-lex.europa.eu/eli/dir/2006/112/oj)), 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](/documentation/design/template-formats/xml.md#numbers-and-dates).
-   `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](https://www.nbb.be/en/payments-and-securities/bank-identification-codes) 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:

```text
{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](/documentation/design/substitutions/aliases.md#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](/documentation/design/template-formats/txt.md#loops). 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`](/documentation/design/computation/store-and-transform.md#modify-json-set-relativepath):

-   `{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:

```xml
  <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](/documentation/design/computation/aggregation.md#learn-with-aggsum-partitionby-aggregate-for-independent-groups) and [grouping with `:set`](/documentation/design/computation/store-and-transform.md#transform-json-set-absolutepath-distinct-merge).

### 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](/documentation/design/computation/aggregation.md) and [math formatters](/documentation/design/computation/simple-mathematics.md).

### 6\. Remove the optional elements without value

Peppol rejects empty elements (rule R008). [Conditional blocks](/documentation/design/conditions/conditional-blocks.md#showbegin-showend) 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](/documentation/design/template-formats/xml.md#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:

```xml
  <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](https://xeinkauf.de/xrechnung/). For a German public buyer, `cbc:BuyerReference` holds its Leitweg-ID, and its electronic address on Peppol uses the scheme `0204`.

## Related Examples

- [Factur-X invoice](/examples/factur-x/index.md): DOCX template to PDF.
- [EDIFACT invoice](/examples/edifact-invoice/index.md): TXT template to EDI.
- [Utility invoice with payment slip](/examples/invoice-expert/index.md): DOCX template to PDF.

## Related topics

- [Monthly management report](/examples/monthly-management-report/index.md)
- [Bank statement with page subtotals](/examples/bank-statement-simple/index.md)
- [Checking account statement](/examples/bank-statement-expert/index.md)
- [EDIFACT invoice](/examples/edifact-invoice/index.md)
- [Monthly fund factsheet](/examples/fund-factsheet/index.md)
- [SEPA credit transfer file](/examples/sepa-xml-credit-transfer/index.md)
