UBL (Universal Business Language)

Short definition

UBL (Universal Business Language) is an XML standard for business documents, maintained by the OASIS consortium. UBL covers far more than invoices — it is a family of related schemas: orders, dispatch advice, credit notes, reminders — all sharing common building blocks.

Since UBL 2.1 it has been the preferred syntax in the European Peppol network and one of the two syntaxes permitted for EN 16931-compliant e-invoices.

Structure of a UBL invoice

A UBL document is flatter and more tag-oriented than CII. The root element is Invoice (or CreditNote for credit notes):

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0</cbc:CustomizationID>
  <cbc:ID>2026-0042</cbc:ID>
  <cbc:IssueDate>2026-04-17</cbc:IssueDate>
  <cac:AccountingSupplierParty>…</cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>…</cac:AccountingCustomerParty>
  <cac:InvoiceLine>…</cac:InvoiceLine>
</Invoice>

Two central namespaces appear throughout:

• cbc: — Common Basic Components (simple values like IDs, dates, amounts)
• cac: — Common Aggregate Components (composite blocks such as Party, Address, LineItem)

UBL vs. CII

Both syntaxes carry the same Business Term fields from EN 16931 — they are semantically equivalent. Differences:

	UBL	CII
Publisher	OASIS	UN/CEFACT
Style	flat, pragmatic XML	deeply nested, typed
Commonly used in	Peppol network, Benelux, Nordics	DE/AT/CH, France
Basis for	Peppol BIS Billing 3.0	ZUGFeRD, Factur-X

ERP systems across Northern and Western Europe typically speak UBL natively, while German and French systems often prefer CII.

Where UBL is used

• Peppol BIS Billing 3.0 — the de-facto format across the Peppol network
• XRechnung — UBL is one of the two accepted syntaxes (the other is CII)
• Public procurement in Norway, Denmark, Italy — national mandates frequently require UBL

Generating UBL with the Dokmatiq API

curl -X POST https://api.dokmatiq.com/v1/einvoice/xrechnung \
  -H "Authorization: Bearer $DOKMATIQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "syntax": "UBL",
    "invoice": {
      "id": "2026-0042",
      "issueDate": "2026-04-17",
      "leitwegId": "991-33333TEST-33",
      "seller": { "name": "Example GmbH", "vatId": "DE123456789" },
      "buyer": { "name": "Customer AG" },
      "lines": [{ "description": "Consulting", "quantity": 8, "unitPrice": 120.0 }]
    }
  }'

The API returns UBL XML validated against the Schematron of the target specification. Switching to "syntax": "CII" produces the CII variant from the same input — no information loss, because both carry identical BT fields.

Common pitfalls

1. Missing CustomizationID — without it, recipient systems cannot tell which spec to validate against (Peppol BIS, XRechnung, other)
2. Wrong namespaces — Peppol recipients are strict; OASIS UBL namespaces must match exactly
3. UBL version mismatch — UBL 2.1 vs. 2.2/2.3: 2.1 remains the invoice standard; newer versions run in parallel
4. Leitweg-ID in the wrong field — in UBL it belongs in cbc:BuyerReference, not in an endpoint tag