Custom UBL

Documentation version 1.3 May 12, 2023

Centrop accepts invoices in UBL Invoice 2.1 format (Universal Business Language). This page is a guideline to create your own UBL invoice.

The sections below explain all the components:

Explanation Sample Invoice (PDF And UBL)

In all the sections below, we use examples. These examples correspond to a sample invoice we created in UBL and PDF.

Click here to download the examples (zip format)

Required fields and calculation explaination

We've created an Excel document to explain the field requirements in depth.

Click here to download the the file in Excel format

Start of file

Reference to XML version.

Reference to scheme You can copy this line verbatim. Remember to close the invoice tag at the end of the full file with

<cbc:CustomizationID>
Reference to specification for specific use of UBL.

In case reference to EN16931 only:
<cbc:CustomizationID>urn:cen.eu:en16931:2017</cbc:CustomizationID>

In case reference to EN16931 as well as NLCIUS:
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0</cbc:CustomizationID>

<cbc:ProfileID>
Reference to profile for specific use of UBL. You can copy this line verbatim.

1<?xml version="1.0" encoding="UTF-8"?>
2
3<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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
4    https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd">
5
6<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0</cbc:CustomizationID>
7<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>

General Headers

<cbc:ID>
This is your invoice number. This number must be unique for each invoice. Invoices that already exist will be rejected.

<cbc:IssueDate>
Invoice date yyyy-MM-dd

<cbc:DueDate>
Invoice due date yyyy-MM-dd, this does not need to be present if the total amount of the invoice is negative.

<cbc:InvoiceTypeCode>
380

The code 380 is for a standard invoice. Credit invoices also receive this code, with negative amounts. We do not accept code 381 with a separate schema. If this tag is not present, we always assume code 380.

<cbc:Note>
This is an optional note field; the Centrop Member number may also be placed here.

<cbc:DocumentCurrencyCode>
EUR

<cbc:BuyerReference>
An invoice must contain a BuyerReference and/or an OrderReference. The buyerreference can be used for the Centrop member number.

Other References

Multiple references can be included in the UBL.

Order Reference

If <cbc:BuyerReference> is present, it is optional. Otherwise required.

<cac:OrderReference>
It consists of two parts:

<cbc:ID>
This is the purchase order number issued by the buyer. This may be the Centrop member number.

<cbc:SalesOrderID>
Sales order number, it is issued by the supplier (Optional)

Shipping Advice

This document is also known as Dispatch Advice.

<cac:DispatchDocumentReference> It contains 1 component:

<cbc:ID>
This is the dispatch advice document number, this is optional.

Attachments (PDF) (AdditionalReference)

It is possible to send the original invoice along with the UBL. For security reasons, we do not support UBL with a link to a PDF on an external website. We only support embeddable PDF. The data should be added as Base64. To test, you can use the following website to convert a PDF to Base64. You can then paste the result into the XML document. https://base64.guru/converter/encode/pdf

We support 1 attachment. Multiple attachments will not be processed.

In the example below, there is no valid binary data because it would become too large. The sample file does contain the real data.

 1<cac:AdditionalDocumentReference>
 2     <cbc:ID>invoice-20220142.pdf</cbc:ID>
 3     <cac:Attachment>
 4        <cbc:EmbeddedDocumentBinaryObject mimeCode=”application/pdf” filename=”invoice-20220142.pdf”>
 5
 6     BINARY OBJECT DATA HERE
 7     (EXAMPLE)
 8     i0xLjQKJeLjz9MKMSAwIG9iago8PAovQ3JlYXRvciA8PgovQ
 9     3JlYXRpb25EYXRlIDw0NDNBMzIzMDMxMzQzMDM5MzIzOTMxMzMzN
10
11       </cbc:EmbeddedDocumentBinaryObject>
12    </cac:Attachment>
13
14</cac:AdditionalDocumentReference>

Sender Of The Invoice (AccountingSupplierParty)

Below is the AccountingSupplierParty example. Since most issues speak for themselves, we only cover the discussion points here:

All sender address information is required.

<cac:PartyTaxScheme><cbc:CompanyID>
This is the VAT number of the sender of the invoice. This VAT number is mandatory.

<cac:PartyTaxScheme><cac:TaxScheme><cbc:ID>
This is always VAT and is mandatory.

<cac:PartyLegalEntity><cbc:RegistrationName>
This is the company name as known to the Chamber of Commerce and mandatory.

<cac:PartyLegalEntity><cbc:CompanyID>
Sender’s Chamber of Commerce Number. This is mandatory. schemeID=”0106″ stands for Chamber of Commerce. (ISO 6523 ICD see this list)

<cbc:Telephone>
Sender’s phone number. This field is required.

<cbc:ElectronicMail>
EMail address of the sender. This field is required.

 1<cac:AccountingSupplierParty>
 2    <cac:Party>
 3        <cac:PartyName>
 4            <cbc:Name>Supplier Company B.V.</cbc:Name>
 5        </cac:PartyName>
 6
 7        <cac:PostalAddress>
 8           <cbc:StreetName>Readystreet 9a</cbc:StreetName>
 9           <cbc:CityName>Amsterdam</cbc:CityName>
10           <cbc:PostalZone>9876 YZ</cbc:PostalZone>
11             <cac:Country>
12                <cbc:IdentificationCode>NL</cbc:IdentificationCode>
13             </cac:Country>
14       </cac:PostalAddress>
15
16       <cac:PartyTaxScheme>
17          <cbc:CompanyID>NL123456789B01</cbc:CompanyID>
18             <cac:TaxScheme>
19                <cbc:ID>VAT</cbc:ID>
20             </cac:TaxScheme>
21       </cac:PartyTaxScheme>
22
23       <cac:PartyLegalEntity>
24	      <cbc:RegistrationName>Supplier Company B.V.</cbc:RegistrationName>
25          <cbc:CompanyID schemeID="0106">12345678</cbc:CompanyID>
26      </cac:PartyLegalEntity>
27
28      <cac:Contact>
29          <cbc:Telephone>088 7654321</cbc:Telephone>
30          <cbc:ElectronicMail>info@test.com</cbc:ElectronicMail>
31      </cac:Contact>
32   </cac:Party>
33</cac:AccountingSupplierParty>

Recipient Of The Invoice (AccountingCustomerParty)

Below is the AccountingCustomerParty example. Since most issues speak for themselves, we only cover the discussion points here:

All recipient address information is required.

<cac:PartyTaxScheme>
This section is required only if a VAT number is known. A VAT number of the receiving party is only required if it is a non-Dutch business recipient of the invoice. (According to the rules of the Tax authorities. No rights can be derived from this VAT number explanation).

If no VAT number is known, this entire block should be omitted. This page includes this section. The downloadable example does not include this.

<cbc:ElectronicMail>
EMail address of the recipient. This field is required.

<cac:PartyLegalEntity><cbc:RegistrationName>
This is the company name as known to the Chamber of Commerce and mandatory.

<cac:PartyLegalEntity> <cbc:CompanyID schemeID=”0106″>
According to the official UBL specification, it is mandatory for the recipient to provide a Chamber of Commerce number (schemeID=”0106″) or OIN number (schemeID=”0190″). For Centrop, this is not mandatory. You can enter 00000000 (eight) zeros in this field.

 1<cac:AccountingCustomerParty>
 2
 3     <cac:Party>
 4
 5        <cac:PartyName>
 6           <cbc:Name>UBL Ready</cbc:Name>
 7       </cac:PartyName>
 8
 9	   <cac:PostalAddress>
10          <cbc:StreetName>Demostreet 1</cbc:StreetName>
11          <cbc:CityName>IJmuiden</cbc:CityName>
12          <cbc:PostalZone>1234 AB</cbc:PostalZone>
13             <cac:Country>
14                 <cbc:IdentificationCode>NL</cbc:IdentificationCode>
15             </cac:Country>
16        </cac:PostalAddress>
17
18		<cac:PartyLegalEntity>
19	      <cbc:RegistrationName>UBL Ready</cbc:RegistrationName>
20		  <cbc:CompanyID schemeID="0106">00000000</cbc:CompanyID>
21		</cac:PartyLegalEntity>
22
23        <cac:Contact>
24		    <cbc:Name>John Doe</cbc:Name>
25            <cbc:Telephone>088-1111111</cbc:Telephone>
26            <cbc:ElectronicMail>invoices@ublreadytest.com</cbc:ElectronicMail>
27        </cac:Contact>
28
29     </cac:Party>
30
31</cac:AccountingCustomerParty>

Payment Method (PaymentMeans)

<cac:PaymentMeans>
This block is mandatory.

<cbc:PaymentMeansCode>
This code is required. Use the following codes:

30. = Credit transfer (bank transfer), payment by credit movement of funds from one account to another.
31. = Bank card (credit card payment), payment by means of a card issued by a bank or other financial institution.
32. = Direct debit (automatic collection), the amount is to be, or has been, directly debited to the customer’s bank account.
33. = Standing agreement (contractual – not further specified), the payment means have been previously agreed between seller and buyer and thus are not stated again.
34. = SEPA credit transfer (SEPA bank transfer), credit transfer inside the Single Euro Payment Area (SEPA) system.
35. = SEPA direct debit (SEPA Direct Debit), direct debit inside the Single Euro Payment Area (SEPA) system.

We also accept the following codes. Attention! Officially, Dutch suppliers must use the above codes.

1 = Bank transfer (Credit transfer)
2 = Credit card payment (Payment card information)
3 = Direct debit

1<cac:PaymentMeans>
2	<cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>
3    <cac:PayeeFinancialAccount>
4        <cbc:ID>NL23ABNA0123456789</cbc:ID>
5		<cac:FinancialInstitutionBranch>
6			<cbc:ID>ABNANL2A</cbc:ID>
7		</cac:FinancialInstitutionBranch>
8	</cac:PayeeFinancialAccount>
9</cac:PaymentMeans>

Payment Condition (PaymentTerms)

With payment discounts, the buyer is allowed to deduct a certain percentage of the invoice amount excluding VAT if payment is made within a set number of days. Both the sender and the buyer do assume the VAT amount before the payment discount.

As a starting point, we take an example of an invoice with rates excluding VAT and different VAT rates. And we include a 2% payment discount.

The sender will process this invoice in the accounts according to the above amounts and thus pay the full VAT (0.63 + 15.91). When the invoice is paid, the payment discount is checked and debited if it is assumed to be justified.

The recipient is assumed to book the invoice before deduction of payment discount, that is, according to the above invoice amount. Upon timely payment, the payment discount is then deducted and recorded as additional revenue. The latter has no impact on VAT.

This payment discount can be included in the UBL invoice via the designated “PaymentTerms” specifying the percentage payment discount and the end date.

The end date indicates the last day the payment discount still applies (up to and including, so the payment discount expires on that day, time 23:59).

Assuming invoice date 1-11-2022 and the 14-day period, the end date is 15-11-2022.

<cbc:Note>
Free text explaining the discount.

<cbc:SettlementDiscountPercent>
The agreed discount precentage. Be sure to use a period for decimal numbers.

<cbc:SettlementDiscountAmount currencyID=”EUR”>
The discount amount. This is the percentage of the invoice amount excluding VAT.

<cbc:EndDate>
The date the discount expires. yyyy-MM-dd

1<cac:PaymentTerms>
2    <cbc:Note>For payment within 14 days, 2% payment discount applies</cbc:Note>
3    <cbc:SettlementDiscountPercent>2</cbc:SettlementDiscountPercent>
4    <cbc:SettlementDiscountAmount currencyID="EUR">1.73</cbc:SettlementDiscountAmount>
5    <cac:ValidityPeriod>
6        <cbc:EndDate>2022-11-15</cbc:EndDate>
7    </cac:ValidityPeriod>
8</cac:PaymentTerms>

If no payment discount is agreed upon, the block should be included in the UBL as follows:

1<cac:PaymentTerms>
2          <cbc:Note>Betalingen binnen 30 dagen.</cbc:Note>
3</cac:PaymentTerms>

VAT Totals (TaxTotal)

The VAT Totals block is required. This is used to check the amounts in the overall document.

For each VAT rate, it lists the base, the percentage and the VAT amount.

<cac:TaxTotal><cbc:TaxAmount>
The total of VAT for a currency. Centrop only accepts EUR and no invoices with multiple currencies or currencies other than EUR. This total is the total for all VAT rates. This amount should be rounded to two decimal places.

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal>
The TaxSubTotal is the subtotal of the total VAT based on a VAT rate and consists of several components:

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal><cbc:TaxableAmount currencyID=”EUR”>
The total amount of all invoice lines, discounts and surcharges excluding VAT for a specific VAT rate (For example, the sum of all amounts excluding 9% VAT)

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal><cbc:TaxAmount currencyID=”EUR”>
The total amount of VAT. Under VAT 0%, 0 should then be entered for this amount.

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal><cac:TaxCategory>
This is the VAT regime. This section consists of several elements.

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal><cac:TaxCategory><cbc:Id>
VAT code. In most cases, the “S” of Standard. Applies to VAT High (21%) and VAT Low (9%) rate

Other options include:

Z = Zero rated goods, code specifying that the goods are at a zero rate; Used for goods and services covered by the 0% rate.

E = Exempt from tax, code specifying that taxes are not applicable; Used when VAT is exempt.

AE = VAT Reverse Charge; Used when VAT is reverse-charged to another entrepreneur (domestic). Also used when billing for an intra-community service (ICP). See also “K” below.

G = Free export item, tax not charged, code specifying that the item is free export and taxes are not charged. Used when exporting goods outside the EU.

K = VAT exempt for EEA intracommunity supply of goods and services. A tax category code indicating the item is VAT exempt due to an intracommunity supply in the European Economic Area. Used when invoicing intra-Community goods (ICP). See also “AE” above.

O = Services outside scope of tax. In this case, the services specifically provided are outside the scope of VAT. Consider services provided by foundations. And insofar as there is no VAT number. The effect is almost in line with the “VAT exemption” mentioned above. For TaxCategory, O then applies instead of E.

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal><cac:TaxCategory><cbc:Percent>
VAT Percentage

<cac:TaxTotal><cbc:TaxAmount><cac:TaxSubTotal><cac:TaxCategory><cbc:Percent><cac:TaxScheme><cbc:Id>
Always VAT

Retrieve the TaxSubtotal block for each VAT percentage option.

 1<cac:TaxTotal>
 2<cbc:TaxAmount currencyID="EUR">53.94</cbc:TaxAmount>
 3	<cac:TaxSubtotal>
 4		<cbc:TaxableAmount currencyID="EUR">198</cbc:TaxableAmount>
 5		<cbc:TaxAmount currencyID="EUR">17.82</cbc:TaxAmount>
 6			<cac:TaxCategory>
 7				<cbc:ID>S</cbc:ID>
 8				<cbc:Percent>9.00</cbc:Percent>
 9					<cac:TaxScheme>
10						<cbc:ID>VAT</cbc:ID>
11					</cac:TaxScheme>
12			</cac:TaxCategory>
13	</cac:TaxSubtotal>
14
15	<cac:TaxSubtotal>
16		<cbc:TaxableAmount currencyID="EUR">172</cbc:TaxableAmount>
17		<cbc:TaxAmount currencyID="EUR">36.12</cbc:TaxAmount>
18			<cac:TaxCategory>
19				<cbc:ID>S</cbc:ID>
20				<cbc:Percent>21.00</cbc:Percent>
21					<cac:TaxScheme>
22						<cbc:ID>VAT</cbc:ID>
23					</cac:TaxScheme>
24			</cac:TaxCategory>
25	</cac:TaxSubtotal>
26 </cac:TaxTotal>

Invoice Totals (LegalMonetaryTotal).

This section is a check for all amounts.

<cac:LegalMonetaryTotal>
This block is mandatory.

<cbc:LineExtensionAmount currencyID=”EUR”>
Contains the total of the invoice lines. This is the sum of <cac:InvoiceLine><cbc:LineExtensionAmount currencyID=”EUR”>

<cbc:TaxExclusiveAmount currencyID=”EUR”>
The total amount excluding VAT. The difference with the section above is that this doesn’t only contain a sum of the invoice lines, but also all other amounts such as shipping costs and invoice discount. So in this example we have added 400 euros at line level, there is a 40 euro discount at invoice level (Allowance Total Amount) and there will be an additional 10 euro order fee (Charge Total Amount). The TAX Exclusive amount is then 370 euros.

<cbc:TaxInclusiveAmount currencyID=”EUR”>
The total amount including VAT.

<cbc:AllowanceTotalAmount currencyID=”EUR”>
Total discount at invoice level. This is the total amount of the Amount tag of all Alowances on invoice level (Not invoice line level) where ChargeIndicator = false.

<cbc:ChargeTotalAmount currencyID=”EUR”>
Total charges at invoice level (Such as order charges). This is the total amount of the Amount tag of all Alowances on invoice level (Not invoice line level) where ChargeIndicator = true

<cbc:PayableAmount currencyID=”EUR”>
The total amount to be paid for this invoice. Calculation: TaxInclusiveAmount - PrePaidAmount.

Register Prepayment
If a certain amount for this invoice has already been paid, an additional element can be added, in this example 50 euros is prepaid.
<cbc:PrepaidAmount currencyID=”EUR”>50</cbc:PrepaidAmount currencyID=”EUR”>

The amount stated here must be subtracted from the TaxInclusiveAmount to calculate the PayableAmount. This option is not included in the example.

1<cac:LegalMonetaryTotal>
2    <cbc:LineExtensionAmount currencyID="EUR">400.00</cbc:LineExtensionAmount>
3    <cbc:TaxExclusiveAmount currencyID="EUR">370.00</cbc:TaxExclusiveAmount>
4	<cbc:TaxInclusiveAmount currencyID="EUR">423.94</cbc:TaxInclusiveAmount>
5	<cbc:AllowanceTotalAmount currencyID="EUR">40.00</cbc:AllowanceTotalAmount>
6	<cbc:ChargeTotalAmount currencyID="EUR">10.00</cbc:ChargeTotalAmount>
7	<cbc:PayableAmount currencyID="EUR">423.94</cbc:PayableAmount>
8</cac:LegalMonetaryTotal>

Invoice Lines (InvoiceLine)

We distinguish between two types of invoice lines here for convenience. Invoice lines without discount and invoice lines with discount. In the example you can download, there are first two lines with no discount.

Invoice Lines Without Discount <cac:InvoiceLine>
Each invoice line gets its own InvoiceLine. See also the downloadable example. There is no container for all invoice lines in the UBL specification.

<cac:InvoiceLine><cbc:Id>
Invoice line number. This is mandatory and must be unique for each rule.

<cac:InvoiceLine>
<cbc:InvoicedQuantity unitCode=”ZZ”>
The quantity billed of this product. Minimum 1.00. The unit code is also required.

<cbc:LineExtensionAmount currencyID=”EUR”>
The line amount to be billed. Here the total quantity x price, minus discount is displayed. This is mandatory.

<cac:Item>
Information about the item, product or service being billed. This is mandatory.

<cac:Item><cbc:Description>
Description of the item. This is optional and can contain the description of the product.

<cac:Item><cbc:Name>
The name of the item. This is mandatory and should contain the name of the product.

<cac:Item><cac:SellersItemIdentification><cbc:ID>
Your item number. This is the item number / product number we match to the product list that was uploaded. This is mandatory.

<cac:Item><cac:ClassifiedTaxCategory>
VAT Category information

<cac:Item><cac:ClassifiedTaxCategory><cbc:ID>
VAT code. In most cases, the “S” of Standard. Applies to VAT High (21%) and VAT Low (9%) rate

Other options include:

Z = Zero rated goods, code specifying that the goods are at a zero rate; Used for goods and services covered by the 0% rate.

E = Exempt from tax, code specifying that taxes are not applicable; Used when VAT is exempt.

AE = VAT Reverse Charge; Used when VAT is reverse-charged to another entrepreneur (domestic). Also used when billing for an intra-community service (ICP). See also “K” below.

G = Free export item, tax not charged, code specifying that the item is free export and taxes are not charged. Used when exporting goods outside the EU.

K = VAT exempt for EEA intracommunity supply of goods and services. A tax category code indicating the item is VAT exempt due to an intracommunity supply in the European Economic Area. Used when invoicing intra-Community goods (ICP). See also “AE” above.

O = Services outside scope of tax. In this case, the services specifically provided are outside the scope of VAT. Consider services provided by foundations. And insofar as there is no VAT number. The effect is almost in line with the “VAT exemption” mentioned above. For TaxCategory, O then applies instead of E.

<cac:Item><cac:ClassifiedTaxCategory><cbc:Percent>
The VAT Percentage for this item. If the VAT rate is 0, you must also enter it here.

<cac:Item><cac:ClassifiedTaxCategory><cac:TaxScheme><cbc:ID>
Always use VAT.

<cac:Price>
Price information for the item. This section is mandatory.

<cac:Price><cbc:PriceAmount currencyID=”EUR”>
The price of the product without discounts. Per unit (unit price)

<cac:Price><cbc:BaseQuantity unitCode=”ZZ”>
The quantity on which the price is based. This is mandatory and in almost all cases 1. This number must not be negative.

 1<cac:InvoiceLine>
 2		<cbc:ID>5</cbc:ID>
 3		
 4		<cbc:InvoicedQuantity unitCode="ZZ">1.00</cbc:InvoicedQuantity>
 5		<cbc:LineExtensionAmount currencyID="EUR">50.00</cbc:LineExtensionAmount>
 6		
 7		<cac:Item>
 8			<cbc:Description>Book The digital highway in Holland</cbc:Description>
 9			<cbc:Name>The digital highway</cbc:Name>
10			<cac:SellersItemIdentification>
11				<cbc:ID>BK0232</cbc:ID>
12			</cac:SellersItemIdentification>
13			<cac:ClassifiedTaxCategory>
14				<cbc:ID>S</cbc:ID>
15				<cbc:Percent>9.00</cbc:Percent>
16				<cac:TaxScheme>
17					<cbc:ID>VAT</cbc:ID>
18				</cac:TaxScheme>
19			</cac:ClassifiedTaxCategory>
20		</cac:Item>
21		
22		<cac:Price>
23			<cbc:PriceAmount currencyID="EUR">50.00</cbc:PriceAmount>
24			<cbc:BaseQuantity unitCode="ZZ">1.00</cbc:BaseQuantity>
25		</cac:Price>
26
27	</cac:InvoiceLine>

Submit Tag Code, Brand And BonusType

If you have new products and they are not yet in the product list, the invoice is imported and the product is added to the list with the note that the tag code is missing. You must then assign it to the new product afterwards. This also applies to the BonusType.

It is also possible to include tag codes, brands and bonus types in the invoice. Then if there is a missing product in the list it will be added including tag code, brand and bonus type and you do not need to do anything else.

See the example in the invoiceline below on how to do this in the section <cac:AdditionalItemProperty> If you are not using this option, omit it. Existing products are not overwritten with new tag codes and/or bonus types. Only missing products are added with the named tag code and bonus type. Brand will be overwritten.

To take advantage of this option, you must provide TagCode and BonusType values. Brand is optional

 1<cac:InvoiceLine>
 2	<cbc:ID>10</cbc:ID>
 3	<cbc:InvoicedQuantity unitCode="ZZ">2.00</cbc:InvoicedQuantity>
 4	<cbc:LineExtensionAmount currencyID="EUR">170.00</cbc:LineExtensionAmount>
 5
 6		<cac:Item>
 7
 8			<cbc:Description>Book Coding UBL for orders and invoices</cbc:Description>
 9			<cbc:Name>Coding UBL</cbc:Name>
10				<cac:SellersItemIdentification>
11					<cbc:ID>BK3025</cbc:ID>
12				</cac:SellersItemIdentification>
13				<cac:ClassifiedTaxCategory>
14					<cbc:ID>S</cbc:ID>
15					<cbc:Percent>9.00</cbc:Percent>
16						<cac:TaxScheme>
17							<cbc:ID>VAT</cbc:ID>
18						</cac:TaxScheme>
19				</cac:ClassifiedTaxCategory>
20
21				<cac:AdditionalItemProperty>
22					<cbc:Name>TagCode</cbc:Name>
23					<cbc:Value>4581</cbc:Value>
24				</cac:AdditionalItemProperty>
25
26				<cac:AdditionalItemProperty>
27					<cbc:Name>BonusType</cbc:Name>
28					<cbc:Value>0</cbc:Value>
29				</cac:AdditionalItemProperty>
30
31				<cac:AdditionalItemProperty>
32					<cbc:Name>Brand</cbc:Name>
33					<cbc:Value>Example Brand</cbc:Value>
34				</cac:AdditionalItemProperty>
35
36		</cac:Item>
37
38		<cac:Price>
39			<cbc:PriceAmount currencyID="EUR">85.00</cbc:PriceAmount>
40			<cbc:BaseQuantity unitCode="ZZ">1.00</cbc:BaseQuantity>
41		</cac:Price>
42
43</cac:InvoiceLine>

Discounted Invoice Lines

The third line in the downloadable example is a discount line. This rule is the same as without crocking with an extra block. In the example below, we have a product that costs 200 euros and is discounted 10%.

<cac:AllowanceCharge>
This block shows discount and surcharge at the line level.

<cbc:ChargeIndicator>
ChargeIndicator; determines whether there is a charge or a discount. Surcharge = true, discount = false

<cbc:AllowanceChargeReason>
Reason for discount or surcharge

<cbc:MultiplierFactorNumeric>
Calculation factor for the base amount. Base Amount times Calculation Factor / 100 = Amount (allowance/discount), see below.

<cbc:Amount currencyID=”EUR”>
Amount of discount or surcharge based on the calculation at MultiplierFactorNumeric above. With currencyID (mandatory); currency designation, usually “EUR”.

<cbc:BaseAmount currencyID=”EUR”>
Base amount for the discount or surcharge. With [1 ..1] currencyID; currency designation, always “EUR”. This is also the amount that can count toward the bonus calculation.

 1<cac:InvoiceLine>
 2
 3	<cbc:ID>15</cbc:ID>
 4	<cbc:InvoicedQuantity unitCode="ZZ">1.00</cbc:InvoicedQuantity>
 5	<cbc:LineExtensionAmount currencyID="EUR">180.00</cbc:LineExtensionAmount>
 6
 7		<cac:AllowanceCharge>
 8			<cbc:ChargeIndicator>false</cbc:ChargeIndicator>
 9			<cbc:AllowanceChargeReason>Price discount</cbc:AllowanceChargeReason>
10			<cbc:MultiplierFactorNumeric>10</cbc:MultiplierFactorNumeric>
11			<cbc:Amount currencyID="EUR">20.00</cbc:Amount>
12			<cbc:BaseAmount currencyID="EUR">200</cbc:BaseAmount>
13		</cac:AllowanceCharge>
14
15		<cac:Item>
16
17			<cbc:Description>Conversion softwarepackage to UBL</cbc:Description>
18			<cbc:Name>Conversion UBL</cbc:Name>
19				<cac:SellersItemIdentification>
20					<cbc:ID>SW4026</cbc:ID>
21				</cac:SellersItemIdentification>
22				<cac:ClassifiedTaxCategory>
23					<cbc:ID>S</cbc:ID>
24					<cbc:Percent>21.00</cbc:Percent>
25						<cac:TaxScheme>
26							<cbc:ID>VAT</cbc:ID>
27						</cac:TaxScheme>
28				</cac:ClassifiedTaxCategory>
29
30				<cac:AdditionalItemProperty>
31					<cbc:Name>TagCode</cbc:Name>
32					<cbc:Value>2812</cbc:Value>
33				</cac:AdditionalItemProperty>
34
35				<cac:AdditionalItemProperty>
36					<cbc:Name>BonusType</cbc:Name>
37					<cbc:Value>1</cbc:Value>
38				</cac:AdditionalItemProperty>
39
40		</cac:Item>
41
42		<cac:Price>
43			<cbc:PriceAmount currencyID="EUR">200.00</cbc:PriceAmount>
44			<cbc:BaseQuantity unitCode="ZZ">1.00</cbc:BaseQuantity>
45		</cac:Price>
46
47</cac:InvoiceLine>

Example 2: Discount with three products

To illustrate, here is a second example, this one is not in the sample ubl. In this example, a 35% discount is given and three products are ordered.

 1<cac:InvoiceLine>
 2	<cbc:ID>1</cbc:ID>
 3	<cbc:InvoicedQuantity unitCode="ZZ">3.00</cbc:InvoicedQuantity>
 4	<cbc:LineExtensionAmount currencyID="EUR">156.00</cbc:LineExtensionAmount>
 5	<cac:OrderLineReference>
 6		<cbc:LineID>1</cbc:LineID>
 7		<cac:OrderReference>
 8			<cbc:ID>273</cbc:ID>
 9			<cbc:SalesOrderID>746191</cbc:SalesOrderID>
10		</cac:OrderReference>
11	</cac:OrderLineReference>
12	<cac:AllowanceCharge>
13		<cbc:ChargeIndicator>false</cbc:ChargeIndicator>
14		<cbc:AllowanceChargeReason>Discount</cbc:AllowanceChargeReason>
15		<cbc:BaseAmount currencyID="EUR">240.00</cbc:BaseAmount>
16		<cbc:MultiplierFactorNumeric>35.00</cbc:MultiplierFactorNumeric>
17		<cbc:Amount currencyID="EUR">84.00</cbc:Amount>	
18	</cac:AllowanceCharge>
19	<cac:Item>
20		<cbc:Description>Product example description</cbc:Description>
21		<cbc:Name>Product name</cbc:Name>
22		<cac:SellersItemIdentification>
23			<cbc:ID>40748190</cbc:ID>
24		</cac:SellersItemIdentification>
25		<cac:ClassifiedTaxCategory>
26			<cbc:ID>S</cbc:ID>
27			<cbc:Percent>21.00</cbc:Percent>
28			<cac:TaxScheme>
29				<cbc:ID>VAT</cbc:ID>
30			</cac:TaxScheme>
31		</cac:ClassifiedTaxCategory>
32	</cac:Item>
33	<cac:Price>
34		<cbc:PriceAmount currencyID="EUR">80.00</cbc:PriceAmount>
35		<cbc:BaseQuantity unitCode="ZZ">1.00</cbc:BaseQuantity>
36	</cac:Price>
37</cac:InvoiceLine>

Explanation:

• The gross price of a product is 80 euros (line 34:PriceAmount).
• The chargeIndicator is set to false, this indicates a discount. (line 13:ChargeIndicator)
• AllowanceChargeReason is the description of the discount (line 14:AllowanceChargeReason)
• To calculate the discount per product, we look at the BaseAmount (line 15:BaseAmount). The BaseAmount is calculated by PriceAmount * InvoicedQuantity
• Next we look at the MultiplierFactor to see what the discount percentage is (line 16:MultiplierFactorNumeric)
• Using the calculation BaseAmount * MultiplierFactorNumeric / 100, we calculate the total discount amount (line 17:Amount)
• The LineExtensionAmount is now calculated using the following formula (InvoicedQuantity * PriceAmount) - Amount (line 4:LineExtensionAmount)

Line level surcharge

It is possible to include a charge at the invoice line level. This is done with the ChargeIndicator. Below is an example of how to add a line-level surcharge.

 1<cac:InvoiceLine>
 2	<cbc:ID>1</cbc:ID>
 3	<cbc:InvoicedQuantity unitCode="ZZ">3.00</cbc:InvoicedQuantity>
 4	<cbc:LineExtensionAmount currencyID="EUR">155.00</cbc:LineExtensionAmount>
 5	<cac:AllowanceCharge>
 6		<cbc:ChargeIndicator>true</cbc:ChargeIndicator>
 7		<cbc:AllowanceChargeReason>Charge</cbc:AllowanceChargeReason>
 8		<cbc:Amount currencyID="EUR">5.00</cbc:Amount>
 9	</cac:AllowanceCharge>
10	<cac:Item>
11		<cbc:Description>Product example description</cbc:Description>
12		<cbc:Name>Product Name</cbc:Name>
13		<cac:SellersItemIdentification>
14			<cbc:ID>40748190</cbc:ID>
15		</cac:SellersItemIdentification>
16		<cac:ClassifiedTaxCategory>
17			<cbc:ID>S</cbc:ID>
18			<cbc:Percent>21.00</cbc:Percent>
19			<cac:TaxScheme>
20				<cbc:ID>VAT</cbc:ID>
21			</cac:TaxScheme>
22		</cac:ClassifiedTaxCategory>
23	</cac:Item>
24	<cac:Price>
25		<cbc:PriceAmount currencyID="EUR">50.00</cbc:PriceAmount>
26		<cbc:BaseQuantity unitCode="ZZ">1.00</cbc:BaseQuantity>
27	</cac:Price>
28</cac:InvoiceLine>

Explanation:

• The gross price of a product is 50 euros (line 25:PriceAmount).
• The chargeIndicator is set to true, this indicates a charge. (line 6:ChargeIndicator)
• AllowanceChargeReason is the description of the allowance (line 7:AllowanceChargeReason)
• Amount is the fixed amount charged as allowance. This may also be a percentage. See the discounts block on how to do this. It works the same way. (Line8:Amount)
• The line amount is now (PriceAmount * InvoicedQuantity) + Amount (line 4:LineExtensionAmount)

Combination of discount and surcharge

It is also allowed to charge discount and allowances on one invoice line. To do this, repeat the <cac:AllowanceCharge> block. Make sure that you do the calculation of the LineExtensionAmount correctly. The amount values of all AllowanceCharge blocks must be included in the calculation.

Credit Invoice Line.

Centrop does not use the UBL CreditNote specification. Instead, credit invoices can be created like a regular invoice with negative numbers. Below is an example of a line indicating a credit. In this example, we are crediting a product costing 75 euros that was ordered twice.

 1<cac:InvoiceLine>
 2	<cbc:ID>2</cbc:ID>
 3	<cbc:InvoicedQuantity unitCode="ZZ">-2</cbc:InvoicedQuantity>
 4	<cbc:LineExtensionAmount currencyID="EUR">-150.00</cbc:LineExtensionAmount>
 5	<cac:Item>
 6		<cbc:Description>Product example description</cbc:Description>
 7		<cbc:Name/>
 8		<cbc:Name>Product name</cbc:Name>
 9		<cac:SellersItemIdentification>
10			<cbc:ID>4888874190</cbc:ID>
11		</cac:SellersItemIdentification>
12		<cac:ClassifiedTaxCategory>
13			<cbc:ID>S</cbc:ID>
14			<cbc:Percent>21</cbc:Percent>
15			<cac:TaxScheme>
16				<cbc:ID schemeAgencyID="6" schemeID="UN/ECE 5153">VAT</cbc:ID>
17			</cac:TaxScheme>
18		</cac:ClassifiedTaxCategory>
19	</cac:Item>
20	<cac:Price>
21		<cbc:PriceAmount currencyID="EUR">75.00</cbc:PriceAmount>
22		<cbc:BaseQuantity unitCode="ZZ">1</cbc:BaseQuantity>
23	</cac:Price>
24</cac:InvoiceLine>

Explanation:

• The gross price of this product is 75 euros, this is a positive number (line 20:PriceAmount)
• The number of products to be credited is 2, note that this is indicated by a negative number (line 3:InvoicedQuantity)
• The LineExtensionAmount is now calculated as usual by InvoicedQuantity * PriceAmount. In this case it will be a negative number (line 4:LineExtensionAmount).

Invoice Allowances And Discount at invoice level (AllowanceCharge)

Invoice surcharges can be, for example, shipping costs. For discounts, we are talking here about discount on the total invoice amount excluding VAT. Because these discounts and costs impact VAT, we must name them somewhere in order to calculate the correct VAT.

We use the AllowanceCharge block for this purpose.

<cac:AllowanceCharge>
In this block, you specify invoice discounts and allowances. You use one block per discount and/or surcharge.

We provide some examples of invoice surcharges and invoice discounts. In general, you are dealing with the following elements:

<Cac:AllowanceCharge><Cbc:ChargeIndicator>
ChargeIndicator; determines whether there is a charge or a discount. Surcharge = true, discount = false

<cac:AllowanceCharge><cbc:AllowanceChargeReason>
Reason for discount or surcharge

<cac:AllowanceCharge><cbc:Amount currencyID=”EUR”>
Bedrag van de korting of toeslag op basis van de berekening bij MultiplierFactorNumeric hierboven. With currencyID (mandatory); currency designation, usually “EUR”.

<cac:AllowanceCharge><cac:TaxCategory>
We need to indicate what VAT rate applies to this surcharge or discount.

<cac:AllowanceCharge><cac:TaxCategory><cbc:ID>
VAT code. In most cases, the “S” of Standard. Applies to VAT High (21%) and VAT Low (9%) rate

Other options include:

Z = Zero rated goods, code specifying that the goods are at a zero rate; Used for goods and services covered by the 0% rate.

E = Exempt from tax, code specifying that taxes are not applicable; Used when VAT is exempt.

AE = VAT Reverse Charge; Used when VAT is reverse-charged to another entrepreneur (domestic). Also used when billing for an intra-community service (ICP). See also “K” below.

G = Free export item, tax not charged, code specifying that the item is free export and taxes are not charged. Used when exporting goods outside the EU.

K = VAT exempt for EEA intracommunity supply of goods and services. A tax category code indicating the item is VAT exempt due to an intracommunity supply in the European Economic Area. Used when invoicing intra-Community goods (ICP). See also “AE” above.

O = Services outside scope of tax. In this case, the services specifically provided are outside the scope of VAT. Consider services provided by foundations. And insofar as there is no VAT number. The effect is almost in line with the “VAT exemption” mentioned above. For TaxCategory, O then applies instead of E.

<cac:AllowanceCharge><cac:TaxCategory><cbc:Percent>
The VAT rate. If this is 0% fill it in here as well.

<cac:AllowanceCharge><cac:TaxCategory><cac:TaxScheme><cbc:ID>
Always VAT

Order Costs

In the example below, we charge a 10 euro order fee.

Please note that in the VAT totals (<cac:TaxTotal>), we must therefore include the amount of this item. So in this case, 21% of 10 euros.

To <cac:LegalMonetaryTotal> add <cbc:ChargeTotalAmount currencyID=”EUR”> with a value of 10 in this example. This is the total of the surcharge (Order Cost).

 1<cac:AllowanceCharge>
 2	<cbc:ChargeIndicator>true</cbc:ChargeIndicator>
 3	<cbc:AllowanceChargeReason>Handling costs</cbc:AllowanceChargeReason>
 4	<cbc:Amount currencyID="EUR">10</cbc:Amount>
 5	<cac:TaxCategory>
 6		<cbc:ID>S</cbc:ID>
 7		<cbc:Percent>21</cbc:Percent>
 8		<cac:TaxScheme>
 9			<cbc:ID>VAT</cbc:ID>
10		</cac:TaxScheme>
11       </cac:TaxCategory>
12</cac:AllowanceCharge>

Invoice Discount

In this example, an invoice discount of 10% is given in addition to the order cost. In this case, it is very important that two VAT rates apply in our example. We have products with 9% VAT and with 21% VAT. This ensures that we need two cac:AllowanceCharge blocks for the 10% bill discount.

Since we are dealing here with a percentage and not a fixed amount as with order fees, we need a little more information.

<cac:AllowanceCharge><cbc:MultiplierFactorNumeric>
In this case, this is the discount percentage. 10% in our example.

<cac:AllowanceCharge><cbc:Amount currencyID=”EUR”>
This is the discount amount in EUR. In this example, 10% of 220 and 10% of 180.

<cac:AllowanceCharge><cbc:BaseAmount currencyID=”EUR”>
This is the amount over which the discount is calculated. In the first case, these are all invoice lines with 9% VAT. This is followed by a new block for 21% VAT rules.

The VAT to add to TaxTotal and LegalMonetaryTotal is the percentage of VAT over Amount. Please note that the amounts do not include VAT.

To <cac:LegalMonetaryTotal> add <cbc:AllowanceTotalAmount currencyID=”EUR”> with a value of 40 in this example. These are the totals of the discounts.

 1<cac:AllowanceCharge>
 2		<cbc:ChargeIndicator>false</cbc:ChargeIndicator>
 3		<cbc:AllowanceChargeReason>Invoice allowance (VAT low 9%)</cbc:AllowanceChargeReason>
 4		<cbc:MultiplierFactorNumeric>10</cbc:MultiplierFactorNumeric>
 5		<cbc:Amount currencyID="EUR">22</cbc:Amount>
 6		<cbc:BaseAmount currencyID="EUR">220</cbc:BaseAmount>
 7		<cac:TaxCategory>
 8			<cbc:ID>S</cbc:ID>
 9			<cbc:Percent>9</cbc:Percent>
10				<cac:TaxScheme>
11					<cbc:ID>VAT</cbc:ID>
12				</cac:TaxScheme>
13		</cac:TaxCategory>
14</cac:AllowanceCharge>
15
16<cac:AllowanceCharge>
17		<cbc:ChargeIndicator>false</cbc:ChargeIndicator>
18		<cbc:AllowanceChargeReason>Invoice allowance (VAT high 21%)</cbc:AllowanceChargeReason>
19		<cbc:MultiplierFactorNumeric>10</cbc:MultiplierFactorNumeric>
20		<cbc:Amount currencyID="EUR">18</cbc:Amount>
21		<cbc:BaseAmount currencyID="EUR">180</cbc:BaseAmount>
22			<cac:TaxCategory>
23				<cbc:ID>S</cbc:ID>
24				<cbc:Percent>21</cbc:Percent>
25					<cac:TaxScheme>
26						<cbc:ID>VAT</cbc:ID>
27				</cac:TaxScheme>
28			</cac:TaxCategory>
29</cac:AllowanceCharge>

UBL Testing

You can use the link below to check if your self-created UBL meets the specifications. https://test.peppolautoriteit.nl/validate

XSD

The XSD of the 2.1 file format can be found here:

https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd