UBL and CII Mapping: Every Key EN 16931 Business Term in Both Syntaxes

The European invoice standard EN 16931 defines one semantic model and two XML syntaxes to write it in. UBL is the syntax of the Peppol network and of much of Northern Europe. UN/CEFACT Cross Industry Invoice (CII) is the syntax inside Factur-X and ZUGFeRD and a common choice in Germany and France. The data is the same; the XML shapes are not. UBL lists flat components such as AccountingSupplierParty and LegalMonetaryTotal, while CII nests the same data inside a trade transaction split into agreement, delivery and settlement.

This reference puts the two side by side for the business terms (BT) and groups (BG) that integrations touch every day. It is the page to keep open when you debug a converted file, explain one to a receiver, or check where a value went. The UBL and CII overviews explain each syntax on its own, and the EN 16931 explainer covers the model behind both.

How to read the mapping

The UBL column gives paths from the root element, Invoice or CreditNote, with the usual cac: (aggregate) and cbc: (basic) prefixes. The CII column gives paths from the root rsm:CrossIndustryInvoice. CII paths get long, so three abbreviations keep the tables readable:

• Agreement stands for rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement: the parties and the references.
• Delivery stands for rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeDelivery: where and when the goods or services went.
• Settlement stands for rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement: currency, payment, VAT and totals.

The authoritative source for every path is the pair of syntax bindings CEN publishes with the standard, EN 16931-3-2 for UBL and EN 16931-3-3 for CII. The tables below cover the terms that carry real data in most invoices; the bindings also list the rarely used ones.

Document header and references

BT-24 decides which rule set a receiver applies, so it is the one value a mapping must never copy blindly between contexts. A Peppol invoice declares the Peppol BIS customization ID, a Factur-X declares its profile URN, and the same invoice moved into the other ecosystem has to declare that ecosystem's identifier.

Seller and buyer

In UBL the seller is cac:AccountingSupplierParty/cac:Party and the buyer cac:AccountingCustomerParty/cac:Party. In CII they are Agreement/ram:SellerTradeParty and Agreement/ram:BuyerTradeParty. Below each party, the structure is the same for seller and buyer, so the table lists the paths relative to the party:

Two rows cause most of the trouble. The legal name sits in PartyLegalEntity in UBL but directly on the party in CII, while the trading name goes the opposite way. And the VAT identifier is told apart from other tax numbers by the TaxScheme in UBL but by a scheme attribute in CII. The electronic addresses are what Peppol routes on; the Factur-X and ZUGFeRD to Peppol guide covers the schemes a participant can be registered under.

Payment instructions

The remittance information is a good example of a value that changes level: UBL keeps it on the payment means, CII on the settlement itself. An account number that is not an IBAN goes into ram:ProprietaryID instead of ram:IBANID on the CII side, while UBL uses the same cbc:ID for both.

Allowances, charges, VAT and totals

The VAT total is where the structures diverge most. UBL puts BT-110 in cac:TaxTotal next to the breakdown and outside LegalMonetaryTotal; CII puts it inside the monetary summation with a currency attribute. When the VAT accounting currency (BT-6) differs from the invoice currency, UBL adds a second cac:TaxTotal and CII a second ram:TaxTotalAmount in that currency (BT-111). The arithmetic rules that tie these totals together, such as BR-CO-15, are identical in both syntaxes.

Invoice lines

A line is cac:InvoiceLine in a UBL invoice, cac:CreditNoteLine in a credit note, and ram:IncludedSupplyChainTradeLineItem in CII for both. CII splits each line into the same agreement, delivery and settlement branches as the header:

Note where the line VAT lives: on the item in UBL, on the line settlement in CII. The price is in the line agreement in CII but a sibling of the item in UBL. Mapping code that walks the two trees in parallel tends to put one of them in the wrong branch.

Where the two syntaxes really differ

Most of the mapping is renaming. These are the places where it is not, and where hand-written XSLT and mapping code usually go wrong:

• One root or two. UBL has separate Invoice and CreditNote documents with different element names (InvoiceLine and CreditNoteLine, InvoicedQuantity and CreditedQuantity). CII has one root and the type code. A UBL to CII mapping reads both documents; a CII to UBL mapping has to choose the UBL document from BT-3.
• Dates. ISO dates in UBL, udt:DateTimeString with format 102 (YYYYMMDD) in CII.
• Tax identifiers. TaxScheme ID VAT in UBL, schemeID VA or FC in CII.
• Names. The legal name moves between the party and its legal entity, and the trading name the other way.
• VAT total and second currency. Outside the monetary total in UBL, inside it in CII, with an extra element for the VAT accounting currency.
• The due date on credit notes. A UBL credit note has no cbc:DueDate; BT-9 goes to the payment means. CII keeps it in the payment terms for both.
• Element order. Both schemas define a fixed sequence. A value in the right element but the wrong position fails schema validation before a single business rule runs.
• BT-24 and BT-23. The identifiers declare the rule set and process. They have to match the target ecosystem, not the source: a CII written into a Factur-X declares a Factur-X profile, a UBL sent over Peppol declares Peppol BIS.

Code lists, by contrast, are shared. VAT categories, payment means codes, units of measure, allowance and charge reason codes and country codes take the same values on both sides, so a mapping never translates codes, only moves them.

Mapping once instead of twice

The cleanest way to support both syntaxes is not to map between them at all, but to map your own data once to the semantic model and let the model produce either syntax. That is how the InvoiceXML create endpoints work: one JSON document model, named after the business terms (invoiceNumber, seller.vatIdentifier, lines[].priceDetails.netPrice), and one endpoint per output. The same JSON posted to /v1/create/ubl returns UBL and posted to /v1/create/cii returns CII, each validated against its rules, and posted to /v1/create/facturx or /v1/create/zugferd it returns the hybrid PDF with the CII inside.

The model also works in the other direction. /v1/extract/json reads a UBL file, a CII file or the XML inside a Factur-X or ZUGFeRD into that same JSON, so an incoming invoice in either syntax lands in one shape in your system. The UBL and CII API toolkits show both directions in code.

Converting without a mapping of your own

When the invoice already exists as XML in one syntax, a conversion endpoint does the whole mapping above in one call, validates the result, and answers with findings instead of a broken file when the source cannot produce a valid one:

• UBL to CII converter: POST /v1/convert/ubl/to/cii takes a UBL invoice or credit note, typically a Peppol BIS document, and returns CII ready for Factur-X or ZUGFeRD embedding or a CII-only system.
• CII to UBL converter: POST /v1/convert/cii/to/ubl returns UBL, and with profile=peppol-bis-3 a Peppol BIS Billing invoice that has passed the Peppol rules.
• For the hybrid formats, UBL to Factur-X covers the PDF/A-3 direction and the Factur-X and ZUGFeRD to Peppol guide the way back onto the network. German public-sector XML goes the same way with the XRechnung to ZUGFeRD converter.

curl -X POST https://api.invoicexml.com/v1/convert/ubl/to/cii \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  --output invoice-cii.xml

curl -X POST https://api.invoicexml.com/v1/convert/cii/to/ubl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "profile=peppol-bis-3" \
  --output invoice-peppol.xml

The mapping tables stay useful even then: when a receiver questions a value, this page tells you where to find it in either file. To check a file you produced yourself, /v1/validate/ubl and /v1/validate/cii run the full rule set and name each finding with its rule and business term.

Get started

Take one invoice you already have in one syntax, convert it to the other, and compare the two files against the tables above: it is the fastest way to learn both shapes. Create a free InvoiceXML account → and get 100 credits for free, no credit card required.

Related resources:

• UBL to CII converter API
• CII to UBL converter API
• XRechnung to ZUGFeRD converter API
• CII explained: the other e-invoicing syntax
• UBL explained: a technical overview
• EN 16931 explained

InvoiceXML is a REST API for European e-invoice compliance covering ZUGFeRD, Factur-X, XRechnung, Peppol UBL, and CII. Stateless processing, GDPR compliant by architecture, and callable from any stack: C#, Node.js, Python, PHP, Java, Go, or anything else with an HTTP client.