VRBL overview

Vertex Universal Standard (VRBL) provides a structured XML format for electronic business documents. You can use it to represent country and mandate-specific information for transformation into the required final format.

Your system must provide complete, internally consistent business information. VRBL also supports inbound conversion and extensions as new mandates and requirements emerge.

Select your country and mandate in the VRBL technical specifications for element definitions, usage, cardinalities, permitted values, and validation rules.

VRBL basic concepts

VRBL uses the following concepts to structure, validate, and transform electronic business documents.

Concept Meaning
Business document An XML file that represents an electronic document, such as an invoice, dispatch advice, or application response.
Document type Identifies the document's purpose and determines its XML structure, including mandatory and optional groups and elements.
Group An XML container node that organises elements and nested groups into a hierarchy.
Element An XML leaf node that holds information within that hierarchy.
Validation Checks the document's structure, syntax, and semantic validity using XML schemas and business rules. The checks depend on the document type and mandate.
Transformation Converts outbound VRBL documents into mandate or platform-specific formats, and inbound documents from those formats into VRBL.

Supported document types

VRBL supports the following document types. Several VRBL document types use the same underlying Universal Business Language (UBL) document type.

Document-type overviews explain how the main components fit together. Use the mandate-specific specifications for the exact fields and rules that apply to your implementation.

VRBL document type UBL document type Purpose
Invoice ubl:Invoice Exchange billing data for invoices, credit notes, and debit notes.
Dispatch Advice ubl:DespatchAdvice Notify a buyer about the dispatch of items and the details of an order.
Waybill ubl:Waybill Provide carriers, consignors, consignees, or authorities with delivery instructions, carriage terms, and shipment details.
Payments Report ubl:Statement Report completed fund transfers, invoice allocations, and account reconciliations.
Rejections Report ubl:Statement Exchange response data that identifies a previously submitted document, reports its rejection, and explains the reasons.
Transactions Report ubl:Statement Provide business partners or regulatory bodies with activity logs and audit trails of commercial transactions over a specified period.
Lifecycle Message ubl:ApplicationResponse Track, report, and audit the processing stages and status changes of a business document throughout its lifecycle.
Compliance Response ubl:ApplicationResponse Communicate regulatory status, tax authority approval, or compliance verification results for a submitted document.
Application Response ubl:ApplicationResponse Notify a sender of a document's acceptance, rejection, or processing status at the application level.

Technical standards and extensions

VRBL combines UBL 2.4 document structures with reusable extensions and mandate-specific rules.

Standard or mechanism Role in VRBL What this means for your implementation
XML Provides the document syntax. Create well-formed XML documents.
UBL 2.4 Defines the underlying document structures and schema cardinalities. Ensure that documents comply with UBL 2.4. Each VRBL invoice instance must conform to the schema for the corresponding UBL 2.4 main document type.
Peppol BIS and Peppol PINT Billing Provide core rules, principles, and structures that VRBL follows where applicable. VRBL deviates where necessary to preserve semantic clarity or support mandates that don't use UBL natively. Follow the applicable VRBL mandate profile, including documented deviations.
VRBL extensions Use UBL 2.4's standard extension containers for additional reusable business terms and groups that base UBL 2.4, Peppol BIS, or Peppol PINT Billing don't cover. Use the components predefined in the VRBL extensions schema.

VRBL extensions

VRBL extension components use the namespace prefix vrbl, mapped to urn:vertexinc:vrbl:ExtensionComponent:1.

Each VRBL extension element or group represents a single, unique context. Its absolute XPath identifies its position within the XML document structure. VRBL extensions represent reusable business terms and business groups, rather than mandate or platform-specific variants. This allows reuse across countries and networks.

Use only the VRBL extensions predefined in the VRBL extensions schema. You can include self-defined extensions in separate extension containers, but validation and transformation ignore them.

Implementation rules and limitations

Each VRBL document targets one mandate. Use the applicable country-specific guide to identify the required information, business rules, and supported fields.

Meet the target mandate's requirements

VRBL lets you provide the elements and groups required by country-specific mandates. However, the target format determines which information the service can pass on. Transformation silently ignores data that has no equivalent in the final format.

Typically, your system generates a VRBL document and sends it to the e-invoicing service. The service validates it and, if validation succeeds, transforms it into the required final format.

When the transformed document also goes to a business recipient, the mandated format may not support all the information you want to exchange. VRBL provides generic elements, such as free-text fields or key-value pairs, to store agreed non-mandated information. Agree on the content and format of these values with the recipient. The target format's limitations still apply.

Use business terms consistently

VRBL defines reusable business terms as leaf elements and business groups as composite structures. The following principles apply:

Mandate-specific requirements and cross-country e-invoicing can make complete semantic separation difficult. In these cases, VRBL prioritises semantic clarity and predictable interpretation. The applicable mandate profile documents any deviations.

Provide complete business information

Calculate all amounts before sending the document. Check that:

Quantities and amounts can be negative.

Target one mandate per document

Each VRBL document instance fulfils exactly one mandate. Its specification identifier defines the semantic requirements and business rules that apply. UBL 2.4 and the VRBL extension schema define the structure and cardinalities.

These rules support development and testing, help detect errors early, and ensure that error messages and rejections refer to the format you provided.

The validation doesn’t fail if you use elements or groups that the mandate doesn’t support. The document must still satisfy the applicable schema and mandate validation rules. Transformation silently ignores elements and groups outside the target mandate's scope.

Specify a receiver

Each VRBL document instance requires exactly one receiver. For outbound documents, a receiver alias identifies the target platform, network, or mandate process.

The receiver alias identifies the processing destination, rather than necessarily identifying the final business recipient. Depending on the implementation and mandate, an authority may forward the transformed document to the business recipient. Alternatively, documents may go directly to the business recipient while a subset of the data goes to the authority.

Plan for format changes

VRBL evolves to support additional country mandates, platforms, processes, and document types. You can decide when to add further mandate coverage based on your business needs and plans.

VRBL processing

For outbound business documents, the service validates the VRBL document, transforms it into the target format, and validates the output where applicable. If any stage detects an error, the service stops processing and reports the error.

The following sequence summarises outbound processing:

  1. The service validates the VRBL document against UBL 2.4 and the VRBL extension schema.
  2. The service validates the document against the VRBL mandate ruleset identified by the document’s specification identifier and receiver.
  3. The service transforms the VRBL document into the final format.
  4. Where applicable, the service validates the final document against the original mandate's schema and ruleset.

After these checks succeed, the document is ready for submission.

For inbound business documents, processing runs in the opposite direction, from the mandate or platform-specific format into VRBL.

Country-specific guides

The country and mandate-specific VRBL specifications explain how to model business documents for individual mandates, countries, platforms, and networks.

Guide terminology

The following terms describe the fields and rules in a country-specific guide. Not every term applies to every element or group.

Term Meaning
Context ID A unique identifier for a VRBL element or group.
XPath An expression that identifies an element or other node in the VRBL XML document.
Cardinality The minimum and maximum number of times an element or attribute can occur, as defined by the XML schema.
Usage An implementation rule that adds business requirements and context to the XML schema's cardinality.
Usage description The business context and conditions that determine when an element or group is required.
Format The nature and format of the value a data point contains.
Mandate business term code The unique code or business term that the target mandate assigns to the corresponding VRBL context.
Final format path The path to the corresponding element, attribute, or data field in the target mandate's final format.

Usage codes

Usage codes indicate whether you must provide an element or group and how often it can occur. In codes that contain n, the guide replaces n with a number. For example, M3 means that three occurrences are mandatory. An element or group can have multiple usage codes. Check the usage description for the applicable conditions and restrictions.

Code Meaning Implementation rule
M Mandatory, once Provide exactly one occurrence.
Mn Mandatory, n times Provide exactly n occurrences.
M+ Mandatory, one or more times Provide at least one occurrence. Repetitions are allowed.
O Optional, once Omit the element or group, or provide one occurrence.
On Optional, up to n times Omit the element or group, or provide up to n occurrences.
O* Optional, zero or more Omit the element or group, or repeat it with no fixed maximum.
C Conditional, once Provide one occurrence if the condition in the usage description applies.
Cn Conditional, n times Provide n occurrences when the applicable condition requires them.
C* Conditional, zero or more Follow the applicable condition. Repetitions have no fixed maximum.

For example, the French CIUS invoice guide specifies M3, C, O* for the Note element. Three notes are mandatory, another note is required under a specified condition, and you can provide additional optional notes. The usage description details the conditions and restrictions.⁠

VRBL invoice overview

A VRBL invoice represents structured electronic billing data for invoices, credit notes, and debit notes. VRBL uses the ubl:Invoice root element for all three document types. The cbc:InvoiceTypeCode element identifies the invoice’s functional type.

Use this overview to understand the core identifiers, calculations, and tax breakdowns. For element definitions, usage, cardinalities, permitted values, and validation rules, select your mandate in the VRBL technical specifications.

Note

The XML examples are partial fragments, not complete documents for submission. They omit namespace declarations and unrelated content. Add the required namespaces and document content before using a fragment in your implementation.

Use the namespace mappings for ubl, cac, and cbc from the applicable VRBL and UBL specifications.

Each example is independent unless the surrounding text states otherwise.

Core identifiers

Provide the following identifiers to specify the document’s mandate specification and business process.

The following fragment shows both identifiers, using the Italian mandate as the example:

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cbc:CustomizationID>urn:vertexinc:vrbl:billing:1#Invoice#VRBL-Invoice-IT-1p2</cbc:CustomizationID>
    <cbc:ProfileID>urn:vertexinc:vrbl:billing:1</cbc:ProfileID>
    <!-- code omitted for clarity -->
</ubl:Invoice>

Specification identifier

Set cbc:CustomizationID to the specification identifier for your target mandate. This identifies the specification whose semantic requirements and business rules the document must follow.

The identifier combines the business process, document type, and country-specific mandate ruleset, separated by #. The following table breaks down the identifier for the Italian mandate.

Segment Value in example Description
Business process urn:vertexinc:vrbl:billing:1 The mandatory fixed prefix.
UBL document type Invoice Identifies the document type.
Mandate ruleset VRBL-Invoice-IT-1p2 The unique country and version string.

XPath: /ubl:Invoice/cbc:CustomizationID

Business process type

The business process type identifies the transaction’s business process. Set cbc:ProfileID to the fixed value urn:vertexinc:vrbl:billing:1.

XPath: /ubl:Invoice/cbc:ProfileID

Calculation principles

Calculate and provide all required amounts before submitting the invoice. Transformation doesn’t calculate missing totals or tax breakdowns.

Calculate item net prices and line net amounts first. Apply document-level allowances and charges, calculate tax breakdowns, then derive the document totals and amount due for payment.

The calculations below use amounts in the document currency. Where an XPath refers to cac:TaxTotal, use the tax total in that currency, not a tax total in a different accounting currency. Check the applicable mandate specification for tax accounting currency requirements and country- or network-specific calculation rules.

Document totals

Calculate document totals from invoice line net amounts, document-level allowances and charges, tax, prepaid amounts, and rounding adjustments. The following example illustrates the document totals. See Tax breakdown calculation example for a separate worked tax calculation.

Example:

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="EUR">1225.00</cbc:TaxAmount>
        <!-- code omitted for clarity -->
    </cac:TaxTotal>
    <!-- code omitted for clarity -->
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="EUR">5900</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="EUR">5900</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="EUR">7125</cbc:TaxInclusiveAmount>
        <cbc:AllowanceTotalAmount currencyID="EUR">200</cbc:AllowanceTotalAmount>
        <cbc:ChargeTotalAmount currencyID="EUR">200</cbc:ChargeTotalAmount>
        <cbc:PrepaidAmount currencyID="EUR">1000</cbc:PrepaidAmount>
        <cbc:PayableRoundingAmount currencyID="EUR">0.02</cbc:PayableRoundingAmount>
        <cbc:PayableAmount currencyID="EUR">6125.02</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
    <!-- code omitted for clarity -->
</ubl:Invoice>

The element names and XPaths identify each total.

Invoice total tax amount

Add the tax amounts from all tax breakdowns.

XPath: /ubl:Invoice/cac:TaxTotal/cbc:TaxAmount

Invoice total tax amount
= sum(all tax category tax amounts)

/ubl:Invoice/cac:TaxTotal/cbc:TaxAmount
= sum(/ubl:Invoice/cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount)

Sum of invoice line net amounts

Add all invoice line net amounts before applying document-level allowances, charges, and tax.

XPath: /ubl:Invoice/cac:LegalMonetaryTotal/cbc:LineExtensionAmount

Sum of invoice line net amounts
= sum(all invoice line net amounts)

/ubl:Invoice/cac:LegalMonetaryTotal/cbc:LineExtensionAmount
= sum(/ubl:Invoice/cac:InvoiceLine/cbc:LineExtensionAmount)

Invoice total amount without tax

Add document-level charges to the sum of invoice line net amounts, then subtract document-level allowances. If you omit a prepaid amount or rounding adjustment, treat it as zero in the calculation.

XPath: /ubl:Invoice/cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount

Invoice total amount without tax
= Sum of invoice line net amounts
- Sum of document-level allowances
+ Sum of document-level charges

/ubl:Invoice/cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
= /ubl:Invoice/cac:LegalMonetaryTotal/cbc:LineExtensionAmount
- sum(/ubl:Invoice/cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount)
+ sum(/ubl:Invoice/cac:LegalMonetaryTotal/cbc:ChargeTotalAmount)

Invoice total amount with tax

Add the invoice total tax amount to the invoice total amount without tax.

XPath: /ubl:Invoice/cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount

Invoice total amount with tax
= Invoice total amount without tax
+ Invoice total tax amount

/ubl:Invoice/cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
= /ubl:Invoice/cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
+ /ubl:Invoice/cac:TaxTotal/cbc:TaxAmount

Sum of document-level allowances

Add all document-level allowance amounts.

XPath: /ubl:Invoice/cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount

Sum of document-level allowances
= sum(all document-level allowance amounts)

/ubl:Invoice/cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount
= sum(/ubl:Invoice/cac:AllowanceCharge[cbc:ChargeIndicator='false']/cbc:Amount)

Sum of document-level charges

Add all document-level charge amounts.

XPath: /ubl:Invoice/cac:LegalMonetaryTotal/cbc:ChargeTotalAmount

Sum of document-level charges
= sum(all document-level charge amounts)

/ubl:Invoice/cac:LegalMonetaryTotal/cbc:ChargeTotalAmount
= sum(/ubl:Invoice/cac:AllowanceCharge[cbc:ChargeIndicator='true']/cbc:Amount)

Amount due for payment

Calculate the final amount payable by subtracting prepaid amounts and adding the rounding adjustment to the invoice total with tax. If you omit a prepaid amount or rounding adjustment, treat it as zero in the calculation.

XPath: /ubl:Invoice/cac:LegalMonetaryTotal/cbc:PayableAmount

Amount due for payment
= Invoice total amount with tax
- Prepaid amount
+ Rounding amount

/ubl:Invoice/cac:LegalMonetaryTotal/cbc:PayableAmount
= /ubl:Invoice/cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
- sum(/ubl:Invoice/cac:LegalMonetaryTotal/cbc:PrepaidAmount)
+ sum(/ubl:Invoice/cac:LegalMonetaryTotal/cbc:PayableRoundingAmount)

Provide any payable rounding adjustment in cac:LegalMonetaryTotal/cbc:PayableRoundingAmount under /ubl:Invoice. Include it in the amount due for payment.

Line-level calculations

Calculate item net prices, invoice line net amounts, and allowances or charges using the following formulas.

Item net price calculation

The following formula applies when you provide an item gross price and a single price-level discount, with no price-level charges. In this case, the item net price equals the gross price minus the discount.

For other cases, such as multiple price-level allowances or price-level charges, follow the applicable mandate’s calculation rules.

XPath: /ubl:Invoice/cac:InvoiceLine/cac:Price/cbc:PriceAmount

Item net price
= Item gross price
- Item price discount

cac:Price/cbc:PriceAmount
= cac:Price/cac:AllowanceCharge/cbc:BaseAmount
- cac:Price/cac:AllowanceCharge/cbc:Amount

The XPath expressions in this formula are relative to /ubl:Invoice/cac:InvoiceLine.

Example:

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:InvoiceLine>
        <!-- code omitted for clarity -->
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">410</cbc:PriceAmount>
            <cbc:BaseQuantity unitCode="C62">1</cbc:BaseQuantity>
            <cac:AllowanceCharge>
                <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
                <cbc:Amount currencyID="EUR">40</cbc:Amount>
                <cbc:BaseAmount currencyID="EUR">450</cbc:BaseAmount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
    <!-- code omitted for clarity -->
</ubl:Invoice>

Invoice line net amount calculation

The invoice line net amount is the net amount excluding tax. It includes line-level allowances and charges.

XPath: /ubl:Invoice/cac:InvoiceLine/cbc:LineExtensionAmount

Invoice line net amount
= (Item net price / Item price base quantity) * Invoiced quantity
+ Sum of invoice line charge amounts
- Sum of invoice line allowance amounts

cbc:LineExtensionAmount
= (cac:Price/cbc:PriceAmount div cac:Price/cbc:BaseQuantity) * cbc:InvoicedQuantity
+ sum(cac:AllowanceCharge[cbc:ChargeIndicator='true']/cbc:Amount)
- sum(cac:AllowanceCharge[cbc:ChargeIndicator='false']/cbc:Amount)

The XPath expressions in this formula are relative to /ubl:Invoice/cac:InvoiceLine. If cac:Price/cbc:BaseQuantity is omitted, use a price base quantity of 1.

Example without line-level allowances or charges:

(200 / 2) × 10
= 1000.00

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:InvoiceLine>
        <cbc:InvoicedQuantity unitCode="C62">10</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
        <!-- code omitted for clarity-->
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">200</cbc:PriceAmount>
            <cbc:BaseQuantity unitCode="C62">2</cbc:BaseQuantity>
        </cac:Price>
    </cac:InvoiceLine>
</ubl:Invoice>

Example with a line-level allowance and charge. This example explicitly sets the price base quantity to one:

(100 / 1) × 10 + 1 − 101
= 900.00

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:InvoiceLine>
        <cbc:InvoicedQuantity unitCode="C62">10</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">900.00</cbc:LineExtensionAmount>
        <!-- code omitted for clarity-->
        <cac:AllowanceCharge>
            <cbc:ChargeIndicator>true</cbc:ChargeIndicator>
            <cbc:AllowanceChargeReasonCode>CG</cbc:AllowanceChargeReasonCode>
            <cbc:AllowanceChargeReason>Charge</cbc:AllowanceChargeReason>
            <cbc:MultiplierFactorNumeric>1</cbc:MultiplierFactorNumeric>
            <cbc:Amount currencyID="EUR">1</cbc:Amount>
            <cbc:BaseAmount currencyID="EUR">100</cbc:BaseAmount>
        </cac:AllowanceCharge>
        <cac:AllowanceCharge>
            <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
            <cbc:AllowanceChargeReasonCode>95</cbc:AllowanceChargeReasonCode>
            <cbc:AllowanceChargeReason>Discount</cbc:AllowanceChargeReason>
            <cbc:Amount currencyID="EUR">101</cbc:Amount>
        </cac:AllowanceCharge>
        <!-- code omitted for clarity-->
        <cac:Price>
            <cbc:PriceAmount currencyID="EUR">100</cbc:PriceAmount>
            <cbc:BaseQuantity unitCode="C62">1</cbc:BaseQuantity>
        </cac:Price>
    </cac:InvoiceLine>
</ubl:Invoice>

Allowance or charge amount calculation

Line-level and document-level allowances and charges can include a base amount and a percentage. If an invoice includes a base amount or percentage for an allowance or charge, it must include both. Use the two values together to calculate the allowance or charge amount. Calculate the amount as follows:

Allowance or charge amount
= Base amount * (Percentage / 100)

cbc:Amount
= cbc:BaseAmount * (cbc:MultiplierFactorNumeric div 100)

The XPath expressions in this formula are relative to the applicable cac:AllowanceCharge element.

Example with a base amount and percentage:

1000 × (20 / 100)
= 200

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:InvoiceLine>
        <!-- code omitted for clarity -->
        <cac:AllowanceCharge>
            <cbc:ChargeIndicator>true</cbc:ChargeIndicator>
            <cbc:AllowanceChargeReasonCode>CG</cbc:AllowanceChargeReasonCode>
            <cbc:AllowanceChargeReason>Cleaning</cbc:AllowanceChargeReason>
            <cbc:MultiplierFactorNumeric>20</cbc:MultiplierFactorNumeric>
            <cbc:Amount currencyID="EUR">200</cbc:Amount>
            <cbc:BaseAmount currencyID="EUR">1000</cbc:BaseAmount>
            <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:AllowanceCharge>
        <!-- code omitted for clarity -->
    </cac:InvoiceLine>
</ubl:Invoice>

Example with an allowance amount only:

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:InvoiceLine>
        <!-- code omitted for clarity -->
        <cac:AllowanceCharge>
            <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
            <cbc:AllowanceChargeReasonCode>95</cbc:AllowanceChargeReasonCode>
            <cbc:AllowanceChargeReason>Discount</cbc:AllowanceChargeReason>
            <cbc:Amount currencyID="EUR">200</cbc:Amount>
            <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:AllowanceCharge>
        <!-- code omitted for clarity -->
    </cac:InvoiceLine>
</ubl:Invoice>

Amount precision

Precision limits don’t define when or how to round intermediate calculations. Follow the applicable mandate specification’s rounding rules.

Use a maximum of two decimal places for the following amounts. The XPath expressions are relative to /ubl:Invoice. Check the applicable mandate specification for exceptions.

Amount Relative XPath
Document-level allowance amount cac:AllowanceCharge[cbc:ChargeIndicator='false']/cbc:Amount
Document-level charge amount cac:AllowanceCharge[cbc:ChargeIndicator='true']/cbc:Amount
Sum of document-level allowances cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount
Sum of document-level charges cac:LegalMonetaryTotal/cbc:ChargeTotalAmount
Invoice total amount without tax cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount
Invoice total tax amount cac:TaxTotal/cbc:TaxAmount
Invoice total amount with tax cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount
Amount due for payment cac:LegalMonetaryTotal/cbc:PayableAmount

Tax information

Tax categories and rates on invoice lines, document-level allowances, and document-level charges determine the document’s tax breakdowns. Use the applicable mandate specification to identify the required exemption information. For invoice lines and document-level allowances or charges that aren’t subject to tax, follow the applicable mandate specification rules on whether to provide a zero rate or omit the rate.

Line tax information

For taxable categories, provide the tax rate in cbc:Percent.

Tax on document-level allowances and charges

Provide the tax category code in cbc:ID within each document-level allowance or charge’s cac:TaxCategory element.

XPath: /ubl:Invoice/cac:AllowanceCharge/cac:TaxCategory

For taxable categories, provide the tax rate in cbc:Percent.

Tax breakdown

Provide one cac:TaxSubtotal for each tax breakdown required by the applicable mandate specification. The examples in this section group invoice lines, document-level allowances, and document-level charges by tax category code and tax rate. If the mandate requires additional grouping criteria, such as tax type or exemption reason, keep those breakdowns separate. Apply all required grouping criteria when calculating the taxable amount for each breakdown. Within each subtotal, cac:TaxCategory identifies the category, rate, and any required tax type or exemption information.

XPath: /ubl:Invoice/cac:TaxTotal/cac:TaxSubtotal

For example, these combinations produce three tax breakdowns.

Tax category Tax rate Taxable amount (EUR) Tax amount (EUR)
S (Standard) 25 percent 1000.00 250.00
S (Standard) 15 percent 1000.00 150.00
E (Exempt) Zero percent 1000.00 0.00

The invoice total tax amount is EUR 400.00, calculated as follows:

250.00 + 150.00 + 0.00
= 400.00

Treat tax rates that differ only in trailing zeros as the same rate. Don’t create separate tax breakdowns solely because of trailing zeros.

For example, two lines with category S and rates of 22 and 22.00 belong to the same tax breakdown if all other grouping criteria required by the mandate also match.

Tax calculation

For each tax breakdown, calculate the taxable amount and tax amount using the formulas that follow.

Tax category taxable amount

Add the invoice line net amounts and document-level charges for the tax breakdown, then subtract the corresponding document-level allowances. Include only amounts that match all grouping criteria required by the mandate in each sum.

XPath: /ubl:Invoice/cac:TaxTotal/cac:TaxSubtotal/cbc:TaxableAmount

Tax category taxable amount
= Sum of invoice line net amounts
+ Sum of document-level charge amounts
- Sum of document-level allowance amounts

Tax category tax amount

Multiply the taxable amount by the tax rate divided by 100.

XPath: /ubl:Invoice/cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount

Tax category tax amount
= Tax category taxable amount
* (Tax category rate / 100)

Invoice total tax amount

Add the tax amounts from all tax breakdowns. The formula and XPath appear in Invoice total tax amount under Document totals.

Tax breakdown calculation example

This example contains three invoice lines, one document-level charge, and one document-level allowance. No additional grouping criteria apply. All amounts use EUR.

Component Amount (EUR) Tax category Tax rate
Line 1 4000.00 S (Standard) 25 percent
Line 2 2000.00 E (Exempt) Zero percent
Line 3 900.00 S (Standard) 25 percent
Document-level charge 200.00 S (Standard) 25 percent
Document-level allowance 100.00 S (Standard) 25 percent

Create two tax breakdowns, one for each category-and-rate combination.

Tax breakdown 1: category S at 25 percent

Tax category taxable amount
= 4000.00 + 900.00 + 200.00 - 100.00
= 5000.00

Tax category tax amount
= 5000.00 * (25 / 100)
= 1250.00

Tax breakdown 2: category E at zero percent

Tax category taxable amount
= 2000.00

Tax category tax amount
= 0.00

Invoice total tax amount

Invoice total tax amount
= 1250.00 + 0.00
= 1250.00

The following XML fragment shows the inputs and tax breakdowns for this calculation.

<ubl:Invoice>
    <!-- code omitted for clarity -->
    <cac:AllowanceCharge>
        <!-- Document Level Charge Amount for category S and rate 25% -->
        <cbc:ChargeIndicator>true</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>Cleaning</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="EUR">200</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID>S</cbc:ID>
            <cbc:Percent>25</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>
    <!-- code omitted for clarity -->
    <cac:AllowanceCharge>
        <!-- Document Level Allowance Amount for category S and rate 25% -->
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>Discount</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="EUR">100</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID>S</cbc:ID>
            <cbc:Percent>25</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>
    <!-- code omitted for clarity -->
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="EUR">1250.00</cbc:TaxAmount>
        <cac:TaxSubtotal>
            <!-- Tax breakdown for category S and rate = 25% -->
            <!-- Taxable amount: lines 1 and 3 + charge - allowance -->
            <cbc:TaxableAmount currencyID="EUR">5000.00</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="EUR">1250.00</cbc:TaxAmount>
            <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:TaxSubtotal>
        <cac:TaxSubtotal>
            <!-- Tax breakdown for category E and rate = 0% -->
            <cbc:TaxableAmount currencyID="EUR">2000.0</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="EUR">0</cbc:TaxAmount>
            <cac:TaxCategory>
                <cbc:ID>E</cbc:ID>
                <cbc:Percent>0</cbc:Percent>
                <!-- Replace this placeholder with the applicable exemption reason. -->
                <cbc:TaxExemptionReason>Applicable exemption reason</cbc:TaxExemptionReason>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:TaxCategory>
        </cac:TaxSubtotal>
    </cac:TaxTotal>
    <!-- code omitted for clarity -->
    <cac:InvoiceLine>
        <cbc:ID>1</cbc:ID>
        <cbc:InvoicedQuantity unitCode="C62">10</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">4000.00</cbc:LineExtensionAmount>
        <!-- code omitted for clarity -->
        <cac:Item>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25.0</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <!-- code omitted for clarity -->
    </cac:InvoiceLine>
    <cac:InvoiceLine>
        <cbc:ID>2</cbc:ID>
        <cbc:InvoicedQuantity unitCode="C62">10</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">2000.00</cbc:LineExtensionAmount>
        <!-- code omitted for clarity -->
        <cac:Item>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>E</cbc:ID>
                <cbc:Percent>0.0</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <!-- code omitted for clarity -->
    </cac:InvoiceLine>
    <cac:InvoiceLine>
        <cbc:ID>3</cbc:ID>
        <cbc:InvoicedQuantity unitCode="C62">10</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="EUR">900.00</cbc:LineExtensionAmount>
        <!-- code omitted for clarity -->
        <cac:Item>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>25.0</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <!-- code omitted for clarity -->
    </cac:InvoiceLine>
</ubl:Invoice>