Odoo guides
OdooUBL 2.1

UBL 2.1 in Odoo

Odoo generates UBL via the OCA account_invoice_ubl module (Community) or built-in Enterprise features. This guide covers the UBL-specific configuration including namespace handling, cbc/cac element mapping, and the often-overlooked journal sequence settings that cause BR-01 (invoice number) violations.

Prerequisites

  • Odoo 16.0 or later with Accounting module fully configured
  • For Community: OCA account_invoice_ubl from github.com/OCA/edi installed
  • Products configured with Internal Reference (maps to UBL SellersItemIdentification)
  • Products with EAN/GTIN barcodes where available (maps to UBL StandardItemIdentification)
  • Journal sequences configured without gaps for BR-01 compliance

Step-by-Step Setup

1

Install OCA account_invoice_ubl module

Download from github.com/OCA/edi → branch matching your Odoo version (e.g., 16.0). Place in custom addons folder. Apps → Update Apps List → search "account_invoice_ubl" → Install. Dependencies account_tax_unece and base_ubl are installed automatically. For Enterprise: this is built-in, just enable Electronic Invoicing in Settings.

2

Configure journal sequence for unique invoice numbers (BR-01)

Invoicing → Configuration → Journals → Customer Invoices journal → Edit. Check "Sequence" settings. Enable "No gaps" if required by your country (Belgium: yes, Netherlands: not required). Invoice numbers must be unique and sequential for BR-01 compliance. Test invoices in dev environments can consume production numbers—use separate database for testing.

3

Map products to UBL item identification

Sales → Products → each product → Edit. "Internal Reference" field maps to cac:SellersItemIdentification/cbc:ID in UBL. "Barcode" field (if EAN-13 format) maps to cac:StandardItemIdentification with schemeID="0088". Products without any identifier generate BR-64 warnings—acceptable but reduces automation capability for receivers.

4

Configure tax codes for UNECE mapping

Invoicing → Configuration → Taxes → Edit each tax. In "Advanced Options" section, set UNECE tax category (S=Standard, Z=Zero, E=Exempt, etc.) and UNECE tax type (VAT). This maps to UBL cac:TaxCategory/cbc:ID. Without UNECE mapping, you get generic "VAT" output that may fail BR-S/BR-Z/BR-E rules.

5

Generate UBL invoice and verify namespace structure

Create invoice → Confirm. Attachments → download UBL XML file. Open in editor and verify: root namespace is "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2", xmlns:cbc for basic components, xmlns:cac for aggregate components. cbc:CustomizationID should contain your target standard (EN16931, Peppol BIS, etc.). Upload to Invoice Navigator for full validation.

Common Odoo Errors

BR-01Missing or Invalid Invoice Number
Full guide →

Why this happens in Odoo

Odoo journal sequences may have gaps or resets. Draft invoices that are cancelled and recreated can cause sequence issues. Also, test invoices during implementation may consume production numbers.

How to fix it

Check Invoicing > Configuration > Journals > Customer Invoices sequence. Ensure "No gaps" is enabled if required. Use separate test database for development.

BR-CO-10Line Calculation Mismatch
Full guide →

Why this happens in Odoo

Default Odoo decimal precision (2 places for Product Price) causes rounding errors with B2B pricing. Common when unit prices have many decimals.

How to fix it

Technical > Decimal Accuracy > Product Price > set to 4+ digits. Re-save affected products and invoices.

BR-64Missing Item Identification
Full guide →

Why this happens in Odoo

Odoo products may lack Standard Item Identification (GTIN/EAN) or Seller Item Identification. Required for some national UBL implementations.

How to fix it

Add product codes: Sales > Products > edit product > Barcode (for GTIN) or Internal Reference (for seller ID).

Pre-Export Checklist for Odoo

Before exporting UBL 2.1 from Odoo, verify these items:

  • 1
    Verify journal sequence has no gaps if required
  • 2
    Confirm decimal accuracy is set to 4+ for Product Price
  • 3
    Ensure products have codes (barcode or internal reference)
  • 4
    Check company legal entity data is complete
  • 5
    Verify customer addresses include postal codes
  • 6
    Test UBL export with a sample invoice

Testing Your Setup

Create a test invoice and check the UBL attachment is generated. Download and inspect XML structure before production use.

💡 OCA account_invoice_ubl module includes test cases. Run Odoo tests to verify your configuration matches expected output.

Validate Your Output

Download UBL attachment from Odoo invoice and upload to Invoice Navigator for validation.

Validate UBL 2.1

FAQ

What is the difference between UBL and EN16931?
UBL 2.1 is the XML syntax/format. EN16931 is the semantic data model that defines required fields and business rules. EN16931 can be expressed in UBL or CII format.
Should I use UBL or CII format?
UBL is more widely adopted, especially for Peppol. Use UBL unless your trading partner specifically requires CII (common in Germany with ZUGFeRD/Factur-X PDF hybrids).

Related Guides

Odoo EN16931 ConfigurationOdoo Peppol Integration

Ready to Test Your Odoo Export?

Upload your UBL 2.1 invoice and get instant compliance feedback with Odoo-specific recommendations.

Validate UBL 2.1 Invoice