UBL Format Guide: Understanding the Peppol Invoice XML Structure

Every Peppol e-invoice is a UBL XML document. The UBL meaning is simple: UBL stands for Universal Business Language, an XML-based standard that defines how invoices, credit notes, and other business documents are structured for exchange across the Peppol network. You will also see it called the UBL formaat or UBL bestand in Dutch and format UBL or facture UBL in French. The underlying file is the same. Whether you are debugging a validation error, building an ERP integration, or simply want to understand what happens under the hood, this guide walks you through the complete UBL invoice structure with practical examples and links to the XSD schema.

1. What is UBL?

UBL stands for Universal Business Language. It is an XML-based standard maintained by OASIS (Organization for the Advancement of Structured Information Standards) for electronic business documents. Think of it as a universal vocabulary for invoices, credit notes, purchase orders, and other commercial documents.

Before UBL, every company and software vendor had their own format for invoices. A Belgian company using one ERP could not automatically exchange invoices with a German company using a different ERP. UBL solves this by defining a single, standardized XML schema that everyone agrees on.

The current version is UBL 2.1, which is the version used by Peppol. It covers over 60 document types, but for e-invoicing, you only need to know about a handful: invoices, credit notes, and debit notes.

So what is the UBL format in practical terms? It is a plain-text XML file that follows the UBL 2.1 XSD schema. The file extension is.xml. A single UBL file holds one business document. In Belgium it is the UBL standard behind every B2B e-invoice sent over Peppol since the January 2026 mandate. The same UBL XML works for Belgian, Dutch, French, and German invoices: there is no country variant of the file itself, only of the business rules layered on top.

The same standard is known under different names in different markets. In the Netherlands it underpins Simpler Invoicing and the NLCIUS profile. In Belgium it is the Peppol BIS Billing 3.0 UBL invoice. In French it is the format UBL, and in Dutch the UBL formaat, UBL bestand, or UBL factuur. All of those words point to the same UBL 2.1 XML document described in this guide.

2. UBL in the Peppol network

Peppol does not use raw UBL. It uses a specific profile called Peppol BIS Billing 3.0, which is built on top of UBL 2.1 and compliant with the European standard EN16931. This means every Peppol invoice must satisfy three layers of rules:

The full document type identifier for a Peppol invoice looks like this:

urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1

This identifier tells the receiving system: "This is a UBL Invoice v2, compliant with EN16931:2017, following Peppol BIS Billing 3.0, using syntax version 2.1."

Where to find the UBL 2.1 XSD schema and Peppol BIS Billing 3.0 rules

The Peppol schema is published in two places. The base UBL invoice XSD lives with OASIS, and the Peppol BIS Billing 3.0 rules live with OpenPeppol:

• UBL 2.1 XSD schema: the structural definition of every element and attribute. Published at docs.oasis-open.org/ubl/os-UBL-2.1. The invoice schema file is UBL-Invoice-2.1.xsd; the credit note schema is UBL-CreditNote-2.1.xsd.
• Peppol BIS Billing 3.0 schematron rules: the business rules on top of the XSD. Published by OpenPeppol at docs.peppol.eu/poacc/billing/3.0, including reference Peppol BIS Billing 3.0 XML examples for every document type.
• EN16931 schematron: the European core rules, published by CEN. These are bundled in the same OpenPeppol validation artifacts so you do not have to fetch them separately.

In practice, most teams never download the XSD. They send their UBL XML to a hosted validator that runs all three layers in one pass. The free Peppol Invoice Viewer does exactly that, and the same checks are exposed through the e-invoice.be API validator endpoint.

3. UBL invoice structure (with XML examples)

The UBL structure consists of six main sections. Let's walk through each one with real XML examples that you can use as reference for your own implementation.

3.1 Header information

The header contains the invoice number, dates, currency, and references. It also includes the CustomizationID and ProfileID that identify this as a Peppol BIS Billing 3.0 document.

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>

  <cbc:ID>INV-2026-001</cbc:ID>
  <cbc:IssueDate>2026-03-01</cbc:IssueDate>
  <cbc:DueDate>2026-03-31</cbc:DueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:Note>Payment within 30 days</cbc:Note>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <cbc:BuyerReference>PO-2026-0042</cbc:BuyerReference>
</Invoice>

The InvoiceTypeCode 380 means a standard commercial invoice. For credit notes, you use a different root element (CreditNote) with type code 381. The BuyerReference is mandatory in Peppol and typically contains the purchase order number or a reference agreed between buyer and seller.

3.2 Party information (seller and buyer)

Every UBL invoice must identify both the seller (AccountingSupplierParty) and the buyer (AccountingCustomerParty). This includes names, addresses, VAT numbers, and optionally Peppol endpoint identifiers.

<!-- Seller -->
<cac:AccountingSupplierParty>
  <cac:Party>
    <cbc:EndpointID schemeID="0208">0123456789</cbc:EndpointID>
    <cac:PartyName>
      <cbc:Name>Acme BVBA</cbc:Name>
    </cac:PartyName>
    <cac:PostalAddress>
      <cbc:StreetName>Koningsstraat 1</cbc:StreetName>
      <cbc:CityName>Brussels</cbc:CityName>
      <cbc:PostalZone>1000</cbc:PostalZone>
      <cac:Country>
        <cbc:IdentificationCode>BE</cbc:IdentificationCode>
      </cac:Country>
    </cac:PostalAddress>
    <cac:PartyTaxScheme>
      <cbc:CompanyID>BE0123456789</cbc:CompanyID>
      <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>
      </cac:TaxScheme>
    </cac:PartyTaxScheme>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Acme BVBA</cbc:RegistrationName>
      <cbc:CompanyID>0123456789</cbc:CompanyID>
    </cac:PartyLegalEntity>
  </cac:Party>
</cac:AccountingSupplierParty>

<!-- Buyer -->
<cac:AccountingCustomerParty>
  <cac:Party>
    <cbc:EndpointID schemeID="0208">0987654321</cbc:EndpointID>
    <cac:PartyName>
      <cbc:Name>Beta NV</cbc:Name>
    </cac:PartyName>
    <cac:PostalAddress>
      <cbc:StreetName>Meir 50</cbc:StreetName>
      <cbc:CityName>Antwerp</cbc:CityName>
      <cbc:PostalZone>2000</cbc:PostalZone>
      <cac:Country>
        <cbc:IdentificationCode>BE</cbc:IdentificationCode>
      </cac:Country>
    </cac:PostalAddress>
    <cac:PartyTaxScheme>
      <cbc:CompanyID>BE0987654321</cbc:CompanyID>
      <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>
      </cac:TaxScheme>
    </cac:PartyTaxScheme>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Beta NV</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:Party>
</cac:AccountingCustomerParty>

The EndpointID with schemeID="0208" is the Peppol participant identifier for Belgian companies. It uses the KBO/BCE enterprise number. For other countries, different scheme IDs apply. Some companies, particularly in retail and healthcare, use a GLN (scheme 0088) instead. Read more in our guide on Peppol Participant Identifiers.

3.3 Payment information

The payment section specifies how the buyer should pay. It includes the payment means code, a payment reference, and optionally the seller's bank account details.

<cac:PaymentMeans>
  <cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
  <cbc:PaymentID>INV-2026-001</cbc:PaymentID>
  <cac:PayeeFinancialAccount>
    <cbc:ID>BE68539007547034</cbc:ID>
    <cbc:Name>Acme BVBA</cbc:Name>
    <cac:FinancialInstitutionBranch>
      <cbc:ID>BBRUBEBB</cbc:ID>
    </cac:FinancialInstitutionBranch>
  </cac:PayeeFinancialAccount>
</cac:PaymentMeans>

<cac:PaymentTerms>
  <cbc:Note>Net 30 days</cbc:Note>
</cac:PaymentTerms>

Payment means code 30 indicates a credit transfer (bank wire). Code 58 is for SEPA credit transfer, which is more specific and commonly used in Europe. The PaymentID is the structured payment reference that appears on the bank statement, making reconciliation easier.

3.4 Invoice lines

Each product or service on the invoice is an InvoiceLine. It contains the item description, quantity, unit price, and the applicable tax category. The line extension amount is the quantity multiplied by the unit price.

<cac:InvoiceLine>
  <cbc:ID>1</cbc:ID>
  <cbc:InvoicedQuantity unitCode="C62">2</cbc:InvoicedQuantity>
  <cbc:LineExtensionAmount currencyID="EUR">500.00</cbc:LineExtensionAmount>
  <cac:Item>
    <cbc:Description>Web development services - March 2026</cbc:Description>
    <cbc:Name>Web Development</cbc:Name>
    <cac:ClassifiedTaxCategory>
      <cbc:ID>S</cbc:ID>
      <cbc:Percent>21</cbc:Percent>
      <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>
      </cac:TaxScheme>
    </cac:ClassifiedTaxCategory>
  </cac:Item>
  <cac:Price>
    <cbc:PriceAmount currencyID="EUR">250.00</cbc:PriceAmount>
  </cac:Price>
</cac:InvoiceLine>

The unitCode attribute uses UN/ECE Recommendation 20 codes. C62 means "unit" (a generic piece/item). See the full unit code reference in section 5 below. The tax category S with 21% is the Belgian standard VAT rate.

3.5 Tax information

The TaxTotal section provides the total tax amount and a breakdown per tax category and rate. If your invoice has lines with different VAT rates, each rate gets its own TaxSubtotal.

<cac:TaxTotal>
  <cbc:TaxAmount currencyID="EUR">105.00</cbc:TaxAmount>
  <cac:TaxSubtotal>
    <cbc:TaxableAmount currencyID="EUR">500.00</cbc:TaxableAmount>
    <cbc:TaxAmount currencyID="EUR">105.00</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:TaxTotal>

The TaxAmount at the top level must equal the sum of all TaxSubtotal amounts. This is one of the EN16931 business rules that validators check. Getting this wrong is one of the most common validation errors.

3.6 Monetary totals

The LegalMonetaryTotal summarizes all amounts on the invoice. It includes the total of all line amounts, the tax-exclusive total, the tax-inclusive total, and the payable amount.

<cac:LegalMonetaryTotal>
  <cbc:LineExtensionAmount currencyID="EUR">500.00</cbc:LineExtensionAmount>
  <cbc:TaxExclusiveAmount currencyID="EUR">500.00</cbc:TaxExclusiveAmount>
  <cbc:TaxInclusiveAmount currencyID="EUR">605.00</cbc:TaxInclusiveAmount>
  <cbc:PayableAmount currencyID="EUR">605.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>

These amounts must be mathematically consistent. LineExtensionAmount is the sum of all InvoiceLine amounts. TaxExclusiveAmount is LineExtensionAmount plus any charges minus any allowances. TaxInclusiveAmount is TaxExclusiveAmount plus the total tax. PayableAmount is what the buyer actually needs to pay (after any prepaid amounts are subtracted).

4. VAT category codes

Every invoice line and tax subtotal must reference a VAT category code. These codes tell the recipient which tax treatment applies. Here are all the codes defined in the Peppol BIS Billing 3.0 specification.

5. Unit codes

Every invoice line needs a unit code in the InvoicedQuantity attribute. These come from UN/ECE Recommendation 20. Here are the most commonly used codes for e-invoicing.

For most service-based businesses, C62 (unit) and HUR (hour) are the only codes you need. The full list contains hundreds of codes, but these ten cover the vast majority of use cases.

6. Document types

UBL defines multiple document types for different business scenarios. The Peppol network supports a growing list, but these are the most relevant for e-invoicing.

For the Belgian e-invoicing mandate, you primarily need Invoice and Credit Note. Self-billing invoices are used in specific scenarios where the buyer creates the invoice. Read our guide on self-billing for details.

7. Attachments

You can embed files in a UBL invoice using the AdditionalDocumentReference element. The file content is base64-encoded and included directly in the XML. Common attachments include a PDF version of the invoice, timesheets, contracts, or delivery receipts. If you only have UBL and need a PDF copy, our Peppol to PDF converter generates one in seconds.

<cac:AdditionalDocumentReference>
  <cbc:ID>ATT-001</cbc:ID>
  <cbc:DocumentDescription>Invoice PDF</cbc:DocumentDescription>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject
      mimeCode="application/pdf"
      filename="INV-2026-001.pdf">
      JVBERi0xLjQKMSAwIG9iago8PC9UeXBlIC9DYXRhbG9n...
    </cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>

The mimeCode tells the recipient what type of file it is. Common values are application/pdf, image/png, and image/jpeg. Keep in mind that attachments increase the document size. Peppol has a maximum message size of approximately 100 MB, but most Access Points recommend keeping it under 10 MB for reliable delivery.

8. Validation rules

Before a UBL invoice can be sent via Peppol, it must pass three layers of validation. If any layer fails, the document is rejected and never delivered.

Common validation errors include:

• Tax amounts that don't add up (the TaxTotal must equal the sum of all TaxSubtotals)
• Missing BuyerReference (mandatory in Peppol even though optional in EN16931)
• Invalid VAT category and percentage combinations (e.g., category AE with a non-zero percentage)
• Line amounts that don't match quantity times unit price
• Missing or invalid EndpointID on parties

The e-invoice.be API validates all three layers automatically before sending. If something is wrong, you get a clear error message explaining exactly which rule failed and how to fix it. You can also use our free UBL checker at Peppol Invoice Viewer to visually inspect and validate UBL documents.

9. The easy way: skip UBL entirely

Understanding UBL is valuable for debugging and integration work. But you do not have to write UBL XML yourself. The e-invoice.be API accepts a simple JSON structure and converts it to a fully validated Peppol BIS Billing 3.0 UBL document automatically.

Here is what the same invoice looks like as a JSON API call:

POST https://api.e-invoice.be/api/documents/
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-03-01",
  "due_date": "2026-03-31",
  "currency": "EUR",
  "vendor_name": "Acme BVBA",
  "vendor_tax_id": "BE0123456789",
  "vendor_address": "Koningsstraat 1, 1000 Brussels, BE",
  "customer_name": "Beta NV",
  "customer_tax_id": "BE0987654321",
  "customer_peppol_id": "0208:0987654321",
  "items": [
    {
      "description": "Web Development",
      "quantity": 2,
      "unit_price": 250.00,
      "tax_rate": 21
    }
  ]
}

That is it. No XML namespaces, no CustomizationID, no TaxScheme elements. The API handles the conversion, validates against all three rule sets, and sends the invoice via Peppol. If the recipient is not on Peppol, you get a clear error before any charge applies.

Read our full API integration guide for code examples in Python, TypeScript, Java, PHP, and Ruby.

UBL meaning: what does UBL stand for?

UBL stands for Universal Business Language. The UBL meaning is exactly what the full form suggests: a single vendor-neutral vocabulary that any business application can use to exchange documents. UBL is an XML standard maintained by OASIS, the same organisation behind SAML and ODF. When people ask "what is UBL", "what does UBL mean", or "what is a UBL file", the short answer is: it is a standardised XML invoice (or credit note, order, despatch advice and so on) used by Peppol BIS Billing 3.0 in Europe and by other frameworks worldwide.

UBL vs XML: are they the same thing?

UBL is not the same as XML. XML is the underlying syntax (a generic markup language). UBL is a specific XML vocabulary: it defines which tags, attributes, and structures are allowed inside an invoice. Every UBL file is XML, but not every XML invoice is UBL. If your ERP produces a custom XML invoice format and you need to send via Peppol, you will need an XML to UBL converter (or a Peppol Access Point that does the conversion). Our API accepts JSON and converts to valid UBL XML automatically, so you never have to hand-write the XSD-compliant schema yourself.

UBL versions: 2.0, 2.1, 2.4, 2.5 and UBL 3.0

UBL has shipped several versions: UBL 2.0 (2006), UBL 2.1 (2013, the current Peppol baseline), UBL 2.2, UBL 2.3, UBL 2.4 and UBL 2.5 (incremental additions of new document types and code lists). UBL 3.0 is in committee draft as of 2026 but is not yet used in production for Peppol BIS Billing 3.0. For Belgian and European Peppol traffic today, you only need to care about UBL 2.1. The official XSD isubl-invoice-2.1.xsdfromOASIS UBL 2.1.

UBL XSD schema and Peppol BIS Billing 3.0 XSD

The UBL 2.1 invoice XSD schema lives in the OASIS UBL 2.1 package. Peppol BIS Billing 3.0 reuses the UBL 2.1 XSD without modification. There is no separate "Peppol BIS Billing 3.0 XSD": validation against Peppol rules is done with Schematron files on top of the UBL 2.1 schema, plus Peppol-specific validation artifacts. The full document type identifier is urn:oasis:names:specification:ubl:schema:xsd:Invoice-2. For UBL CreditNote it is urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2.

UBL in other languages: factuur, facture, factura, Rechnung

The UBL standard is language-neutral, but the search terms vary by country. A UBL factuur (Dutch), facture UBL (French), factura UBL (Spanish) and UBL Rechnung (German) all refer to the same artefact: an EN16931-compliant invoice serialised as UBL 2.1 XML. Specific national CIUSes (customisations) sit on top of UBL: OIOUBL in Denmark, XRechnung UBL in Germany, the French Factur-X relationship (which uses CII rather than UBL, but Peppol Access Points typically convert between the two). Asking "UBL nedir", "UBL formatı nedir", "fatura UBL nedir" (Turkish), "UBL kya hota hai" (Hindi) or "UBL คือ" (Thai)? The answer is the same Universal Business Language defined by OASIS and used by Peppol.

UBL invoice and credit note examples (copy-paste ready)

Looking for a UBL 2.1 invoice example XML, a UBL XML invoice example, a Peppol BIS 3.0 invoice example or a UBL invoice example XML in factura europea UBL format? The sections above walk through a complete UBL invoice example, line by line, with the Peppol BIS Billing 3.0 XML example for header, parties, lines, tax totals and monetary totals. Every snippet is copy-paste ready against theubl-invoice-2.1.xsdand the Peppol BIS Billing 3.0 specification (the official specification PDF is available ondocs.peppol.eu).

Invoice type codes and unit codes in UBL

UBL invoices use UN/CEFACT code lists. The most common InvoiceTypeCode value is 381 for a credit note, 380 for a commercial invoice, and 389 for a self-billed invoice. The default UnitCode for "one piece" is C62 from UN/ECE Recommendation 20. The full Peppol UOM (unit of measure) code list is maintained in the Peppol Code Lists repository. For the InvoiceTypeCode and UnitCode reference (including the [BR-CL-23] rule that the unit code must be coded according to UN/ECE Recommendation 20 with Rec 21 extension), consult the Peppol BIS Billing 3.0 specification.

10. Frequently asked questions

Further resources

• Peppol BIS Billing 3.0 documentation (official Peppol specification)
• OASIS UBL 2.1 standard (UBL invoice 2.1 documentation and full specification)
• E-Invoicing API integration guide (send invoices with JSON, not XML)
• Self-billing guide (how self-billing works with Peppol)
• Peppol Invoice Viewer (visualize and validate UBL documents)