Skip to main content

Overview

The Document schema defines the structure of invoices, credit notes and debit notes in the e-invoice.be API. You send this schema when you call POST /api/documents/ or POST /api/validate/json.
The schema marks no field as required. But the items array must have a minimum of one line (minItems: 1). Always send items with one or more lines. An empty array ("items": []) gives 422. A body with no items key passes the schema check, but the UBL then has no invoice line. POST /api/documents/ returns 406 with a detail that starts with Provided document details lead to an invalid UBL document. POST /api/validate/json returns 201 with is_valid false and an issue with rule_id xsd-validation. All other fields are optional in the schema. But POST /api/documents/ accepts a document only if it also has:
  • A vendor identifier (vendor_tax_id or vendor_company_id) and a customer identifier (customer_peppol_id, customer_tax_id or customer_company_id). The derived Peppol ID of the sender must be one of the peppol_ids of your company (406 if not).
  • invoice_id (rule BR-02) and vendor_name.
  • A description (or name), a quantity and a unit_price for each line. A line without description and name gives 422 with the message Line item needs a name or description (BR-25). A line without quantity or unit_price counts as 0.00 in the totals.
  • For an invoice with a positive amount due: due_date or payment_term (rule BR-CO-25).
When a field is absent, the API uses these values: invoice_date is the current date, unit is NAR, a missing address becomes Unknown Street and Unknown City, and a line with tax_rate 0.00 gets tax category Z when tax_code is S.Each field accepts null, except document_type, state, direction, currency, tax_code and items. For these six fields, null gives 422. To get the default value, omit the field. For example, send no currency field to get EUR, but do not send "currency": null.
Validation is not a separate mandatory call. POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.

Document metadata

enum
default:"INVOICE"
Type of document to create.
  • INVOICE - Standard invoice
  • CREDIT_NOTE - Credit note (refund or correction)
  • DEBIT_NOTE - Debit note
  • SELFBILLING_INVOICE - Self-billed invoice
  • SELFBILLING_CREDIT_NOTE - Self-billed credit note
See Self-billing and debit notes for the two self-billing types and for debit notes.
enum
default:"DRAFT"
Document state. See Document states. Read-only: POST /api/documents/ always sets DRAFT and ignores the value that you send.
enum
default:"OUTBOUND"
Document direction. Read-only: POST /api/documents/ always sets OUTBOUND and ignores the value that you send.
  • OUTBOUND - Document that you send to a customer
  • INBOUND - Document that you receive from a supplier

Document states

You can send a document only when it is in the DRAFT or FAILED state. For the transitions, the retry behaviour and the webhook events of each state, see Document lifecycle and delivery tracking. See Document lifecycle and delivery tracking for the state diagrams, the transitions, the retries and the related webhook events.

Vendor (supplier) information

string
Legal name of the vendor.Example: "E-INVOICE BV"
string
VAT number of the vendor, with the country prefix. The API changes the value to uppercase and removes all characters other than A-Z and 0-9. See Normalisation and rounding.Example: "BE1018265814"The API derives the Peppol ID of the vendor from this value. For the document types other than self-billing, the vendor is the Peppol sender. See Peppol ID routing.
string
Company registration number of the vendor, for example the Belgian enterprise number (CBE), the European Unique Identifier (EUID) or the Dutch KVK number. The API uses it to derive the Peppol ID of the vendor when vendor_tax_id is absent.Example: "1018265814"
string
Address of the vendor as one string. See Addresses for the format that the API can split correctly.Example: "Brusselsesteenweg 119/A, 1980 Zemst, BE"
string
Department or person at the vendor address. The API also writes this value as the seller contact name (BT-41) to cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name.When the vendor and the customer are both in Germany, this field is necessary (rule DE-R-005). See vendor_phone.Example: "Accounts Department"
string
Contact email address of the vendor.Example: "billing@e-invoice.be"
string
Telephone number of the seller contact (BT-42). Optional; the value can be null. The API writes it to cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Telephone. The API does not change the value.Example: "+49 30 1234567"When the vendor and the customer are both in Germany, the UBL must have a seller contact with a name, a telephone number and an email address. Send vendor_address_recipient (rule DE-R-005), vendor_phone (rule DE-R-006) and vendor_email (rule DE-R-007). If one is absent, the API returns 406. A telephone number with fewer than 3 digits gives only a warning (rule DE-R-027).

Customer (buyer) information

string
Legal name of the customer.Example: "OpenPeppol VZW"
string
VAT number of the customer, with the country prefix. The API changes the value to uppercase and removes all characters other than A-Z and 0-9.Example: "BE0848934496"
string
Company registration number of the customer, for example the CBE number, the EUID or the KVK number. The API uses it to derive the Peppol ID of the customer when customer_peppol_id and customer_tax_id are absent.Example: "0848934496"
string
Peppol participant ID of the customer, in the format scheme:identifier. When you send this field, the API uses it as the Peppol ID of the customer and does not derive it from customer_tax_id or customer_company_id. The customer is the Peppol receiver, except in a self-billing document, where the customer is the Peppol sender.Example: "0208:0848934496"The API does not store this field with the document. The value is kept only as the receiver of the generated UBL. The DocumentResponse schema has the field, but GET /api/documents/{document_id} does not return it, and a list returns it as null. See Look up Peppol participants to find and check a Peppol ID before you send.
string
Your internal reference for the customer. The API writes it as the party identification of the customer. It is also the fallback value of BuyerReference when buyer_reference and purchase_order are absent. The API does not use it to find the Peppol ID of the customer.Example: "CUST-12345"
string
Address of the customer as one string. See Addresses.Example: "Rond-point Schuman 6, 1040 Brussels, BE"
string
Department or person at the customer address. The API also writes this value as the buyer contact name (BT-56) to cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Name.Example: "Accounts Payable"
string
Contact email address of the customer.Example: "ap@openpeppol.example"
string
Telephone number of the buyer contact (BT-57). Optional; the value can be null. The API writes it to cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:Telephone. The API does not change the value.Example: "+49 89 7654321"

Invoice details

string
Unique invoice number.Example: "INV-2026-001"
string
Issue date in ISO 8601 format (YYYY-MM-DD). When it is absent, the API uses the current date.Example: "2026-10-01"
string
Payment due date in ISO 8601 format (YYYY-MM-DD). The API does not write this field to the UBL of a credit note.Example: "2026-10-31"
string
Buyer reference (BT-10), for example a cost centre or a reference that the buyer asks for. The API writes it to cbc:BuyerReference.Example: "CC-4410"
string
Purchase order reference of the customer (BT-13). The API writes it to cac:OrderReference/cbc:ID, and to cbc:BuyerReference when buyer_reference is absent. Do not use it for the number of the original invoice of a credit note: use preceding_invoice_id.Example: "PO-12345"
string
Sales order reference of the vendor (BT-14). The API writes it to cac:OrderReference/cbc:SalesOrderID. When purchase_order is absent, the API writes NA as the order reference ID.Example: "SO-2026-0042"
string
Number of the invoice that this document corrects (BT-25), for example the invoice that a credit note credits. The API writes it to cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID.The API removes the spaces at the start and at the end of the value. A value with only spaces, for example " ", becomes null.Example: "INV-2026-001"
string
Issue date of the preceding invoice (BT-26) in ISO 8601 format (YYYY-MM-DD). The API writes it only together with preceding_invoice_id.Example: "2026-10-01"
string
Free-text note.Example: "Full refund - goods returned"
string
Description of the payment terms.Example: "Payment due within 30 days"

Financial fields

The API calculates subtotal, total_discount, total_tax, invoice_total and amount_due when they are absent. When you send them, the API compares them with its own calculation. The API does not calculate rounding_amount. See Invoice totals and calculations for the formulas. You can send each amount as a JSON number (1210.00) or as a string ("1210.00"). The response gives each amount as a string. For an amount with no value, see Response fields.
enum
default:"EUR"
Currency code (ISO 4217).The currency field accepts these ISO 4217 codes:EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, SEK, NOK, DKK, SGD, HKDThe default is EUR.Example: "EUR"
number | string
Taxable base amount (after document-level allowances and charges, before tax).Corresponds to UBL cac:LegalMonetaryTotal/cbc:TaxExclusiveAmountExample: 1000.00
number | string
Total of the document-level allowances (discounts only, not charges).Corresponds to UBL cac:LegalMonetaryTotal/cbc:AllowanceTotalAmountExample: 50.00
number | string
Total VAT amount.Corresponds to UBL cac:TaxTotal/cbc:TaxAmountExample: 210.00
string
VAT accounting currency (BT-6), as an ISO 4217 code of 3 capital letters. Optional; the value can be null. The API writes it to cbc:TaxCurrencyCode. A code in lowercase letters, for example "eur", gives 422.Use it only when the vendor must account the VAT in a currency other than currency. For example, a Belgian vendor sends an invoice in USD and accounts the VAT in EUR. See VAT in a different currency.Example: "EUR"
number | string
Total VAT amount in the tax_currency (BT-111). Optional; the value can be null. Send a maximum of 2 decimals. The API writes it to a second cac:TaxTotal/cbc:TaxAmount, with currencyID set to tax_currency.The value is for information only. It does not change total_tax, invoice_total or amount_due. The API does not convert currencies and does not compare this value with total_tax.Example: 193.20

VAT in a different currency

Send tax_currency and total_tax_in_tax_currency together. The other amounts stay in currency. These rules apply. If a rule fails, the API returns 422, and the msg of the error contains the message in the table. Example: an invoice of 1000.00 USD with 21% VAT. The vendor accounts the VAT in EUR. The VAT is 210.00 USD, which is 193.20 EUR at the exchange rate of the vendor.
The UBL then has two cac:TaxTotal elements. The first has the tax breakdown in the document currency. The second has only the amount in the VAT accounting currency (rules PEPPOL-EN16931-R053 and PEPPOL-EN16931-R054).
On a received document, the API fills the two fields from cbc:TaxCurrencyCode and the second cac:TaxTotal. total_tax keeps the amount in the document currency.
number | string
Total amount with tax (subtotal + total_tax). It does not include rounding_amount.Corresponds to UBL cac:LegalMonetaryTotal/cbc:TaxInclusiveAmountExample: 1210.00
number | string
Amount that the customer must pay (BT-115).Corresponds to UBL cac:LegalMonetaryTotal/cbc:PayableAmount
  • When amount_due is absent, the API uses invoice_total + rounding_amount.
  • A lower value states a prepayment. If the difference is more than 0.01, the API writes it as cac:LegalMonetaryTotal/cbc:PrepaidAmount.
  • A value more than invoice_total + rounding_amount + 0.01 gives 406.
Example: 1210.00Example of a prepayment: the customer paid 210.00 in advance on an invoice total of 1210.00.
The API writes this UBL:
number | string
Amount that the API adds to invoice_total to get a rounded amount for payment (BT-114). For example, use it to round to whole kronor.Corresponds to UBL cac:LegalMonetaryTotal/cbc:PayableRoundingAmount
  • The value is from -5.00 to 5.00. It can be negative.
  • The value has a maximum of 2 decimals. A value out of range or with more decimals gives 422.
  • A JSON number with a floating-point error is accepted. For example, -0.6000000000000227 (the result of Math.round(total) - total in JavaScript) becomes -0.60. A real third decimal, for example -0.605, gives 422.
  • When it is absent, the value is 0. The API writes the UBL element only when the value is not 0.
  • It does not change subtotal, total_tax or invoice_total. It changes only amount_due.
When nothing is prepaid, amount_due = invoice_total + rounding_amount. Send an amount_due that includes the rounding amount, or omit amount_due. If rounding_amount is not 0 and amount_due is equal to invoice_total, the API returns 406.Example: round an invoice total of 1210.47 down to 1210.00.
See Rounding amount.
number | string
Previous outstanding balance. This is an internal field: the API does not write it to the generated UBL, and the response does not contain it.Example: 100.00

Tax information

enum
default:"S"
Tax category code (UNCL5305).
  • S - Standard rate (most common)
  • Z - Zero rated
  • E - Exempt from tax
  • AE - VAT reverse charge
  • K, G, O, L, M, B - Other special cases
The API derives the tax category of each line from its tax_rate: a rate more than 0.00 gives S. A rate of 0.00 gives the tax_code of the document, or Z when tax_code is S.When tax_code is K (intra-community supply), each line item must have a tax_rate of 0.00 (422 if not). For example, "tax_code": "K" with a line "tax_rate": 21.00 gives 422. The msg of the error contains When tax_code is 'K' (intra-community supply), all line item tax_rate must be 0.00.
enum
VAT exemption reason code (BT-121), from the VATEX code list.An exemption reason is vatex or vatex_note. One of the two is sufficient. The reason is required when tax_code is E, AE, K, G or O. It is not permitted when tax_code is S, Z, L or M. See VAT exemption reason.Example: "VATEX-EU-IC" for an intra-community supply, "VATEX-EU-AE" for a reverse chargeWhen vatex is VATEX-EU-O (not subject to VAT), vendor_tax_id and customer_tax_id must be empty (406 if not). Use vendor_company_id to identify the vendor. For example, "vatex": "VATEX-EU-O" with "vendor_tax_id": "BE1018265814" and no customer_tax_id gives 406 with this detail:
The API accepts only the codes of the VATExemptionCode list. See VAT exemption codes.
string
VAT exemption reason text (BT-120). The same rule applies as for vatex: the reason is required when tax_code is E, AE, K, G or O, and one of the two fields is sufficient. Do not send vatex_note when tax_code is S, Z, L or M. See VAT exemption reason.When you send vatex_note, the UBL contains only this text as the exemption reason, and not the vatex code.Example: "Reverse charge applies - Art. 196 EU VAT Directive"

VAT exemption reason

An exemption reason is the code in vatex (BT-121) or the text in vatex_note (BT-120). One of the two is sufficient. The tax_code of the document controls the rule: tax_code, vatex and vatex_note are fields of the document. A line item does not have these fields. Valid: an exempt invoice with a reason code.
Also valid: the same invoice with a reason text and no code.
Not permitted: a standard-rate invoice with an exemption reason.
The API does not make this check on the JSON. It applies the EN 16931 rules to each tax group of the generated UBL:
  • A line with a tax_rate of 0.00 is in a group with the category of tax_code, or Z when tax_code is S. The API writes the exemption reason to this group.
  • A line with a tax_rate more than 0.00 is in a group with the category S. The API writes no exemption reason to this group and returns no error. The receiver does not get the exemption reason.
If a group does not obey a rule, POST /api/documents/ returns 406. The detail starts with Provided document details lead to an invalid UBL document and contains the message of the rule. POST /api/validate/json returns 201 with is_valid false and an issue with the rule_id of the rule.

VAT exemption codes

vatex accepts these 88 codes (VATExemptionCode): VATEX-EU-79-C, VATEX-EU-132, VATEX-EU-132-1A, VATEX-EU-132-1B, VATEX-EU-132-1C, VATEX-EU-132-1D, VATEX-EU-132-1E, VATEX-EU-132-1F, VATEX-EU-132-1G, VATEX-EU-132-1H, VATEX-EU-132-1I, VATEX-EU-132-1J, VATEX-EU-132-1K, VATEX-EU-132-1L, VATEX-EU-132-1M, VATEX-EU-132-1N, VATEX-EU-132-1O, VATEX-EU-132-1P, VATEX-EU-132-1Q, VATEX-EU-135-1, VATEX-EU-143, VATEX-EU-143-1A, VATEX-EU-143-1B, VATEX-EU-143-1C, VATEX-EU-143-1D, VATEX-EU-143-1E, VATEX-EU-143-1F, VATEX-EU-143-1FA, VATEX-EU-143-1G, VATEX-EU-143-1H, VATEX-EU-143-1I, VATEX-EU-143-1J, VATEX-EU-143-1K, VATEX-EU-143-1L, VATEX-EU-144, VATEX-EU-146-1E, VATEX-EU-148, VATEX-EU-148-A, VATEX-EU-148-B, VATEX-EU-148-C, VATEX-EU-148-D, VATEX-EU-148-E, VATEX-EU-148-F, VATEX-EU-148-G, VATEX-EU-151, VATEX-EU-151-1A, VATEX-EU-151-1AA, VATEX-EU-151-1B, VATEX-EU-151-1C, VATEX-EU-151-1D, VATEX-EU-151-1E, VATEX-EU-153, VATEX-EU-159, VATEX-EU-309, VATEX-EU-AE, VATEX-EU-D, VATEX-EU-F, VATEX-EU-G, VATEX-EU-I, VATEX-EU-IC, VATEX-EU-O, VATEX-EU-J, VATEX-FR-298SEXDECIESA, VATEX-FR-AE, VATEX-FR-CGI261-1, VATEX-FR-CGI261-2, VATEX-FR-CGI261-3, VATEX-FR-CGI261-4, VATEX-FR-CGI261-5, VATEX-FR-CGI261-7, VATEX-FR-CGI261-8, VATEX-FR-CGI261A, VATEX-FR-CGI261B, VATEX-FR-CGI261C-1, VATEX-FR-CGI261C-2, VATEX-FR-CGI261C-3, VATEX-FR-CGI261D-1, VATEX-FR-CGI261D-1BIS, VATEX-FR-CGI261D-2, VATEX-FR-CGI261D-3, VATEX-FR-CGI261D-4, VATEX-FR-CGI261E-1, VATEX-FR-CGI261E-2, VATEX-FR-CGI275, VATEX-FR-CGI277A, VATEX-FR-CGI295, VATEX-FR-FRANCHISE, VATEX-FR-CNWVAT

Service period

string
Start date of the service period (ISO 8601: YYYY-MM-DD).Example: "2026-09-01"
string
End date of the service period (ISO 8601: YYYY-MM-DD).Example: "2026-09-30"

Additional addresses

Of these fields, the API writes only shipping_address and shipping_address_recipient to the generated UBL (as cac:Delivery). The billing, service and remittance fields are kept with the document, but the receiver does not get them in the UBL.
string
Billing address (if different from the customer address).Example: "Rond-point Schuman 6, 1040 Brussels, BE"
string
Recipient at the billing address.Example: "Accounts Payable Department"
string
Deliver-to address (BG-15). The API writes it to cac:Delivery/cac:DeliveryLocation/cac:Address. The split rule is different from the rule for the vendor and customer addresses. See Shipping address.When the address has no country code, the API uses the country of the customer. When tax_code is K and there is no shipping address, the API writes only the country of the customer as the delivery location.Example: "Industrieweg 5, 3000 Leuven, BE"
string
Name of the deliver-to party (BT-70), for example the name of the company or the site that receives the goods. The API writes it to cac:Delivery/cac:DeliveryParty/cac:PartyName/cbc:Name. The API writes this element also when shipping_address is absent.On a received document, the API fills this field from the same UBL element. For a received CII document, the source is the name of the ship-to trade party.Example: "OpenPeppol VZW - Warehouse"
string
Address of the service location.Example: "Industrieweg 5, 3000 Leuven, BE"
string
Recipient at the service address.
string
Remittance (payment) address.Example: "Brusselsesteenweg 119/A, 1980 Zemst, BE"
string
Recipient at the remittance address.

Line items

array
Array of line items. The array must have a minimum of one line (minItems: 1). The schema does not list items as a required field, but always send one or more lines.See the LineItem schema for the fields.Example:

Payment details

array
Array of payment instructions. The API writes one cac:PaymentMeans element for each entry, always with payment means code 30 (credit transfer).Example:
Example for a Swedish vendor with a bankgiro number. The API stores bank_account_number as "50501055":
The API writes this UBL:
For a Swedish vendor, the Peppol rules check the number. A bankgiro number has 7 or 8 digits. A plusgiro number has 2 to 8 digits. A different number gives a warning only (rules SE-R-007 to SE-R-010).

Allowances and charges

In an allowance or a charge, send amount, base_amount, multiplier_factor and tax_rate as JSON numbers. A string that is not a number gives 500, not 422. For example, "multiplier_factor": "abc" or "tax_rate": "21%" gives 500 with the detail Internal server error.
array
Document-level allowances (discounts).Example of a 10% allowance:
array
Document-level charges (fees).Example:
See Advanced invoicing for the effect of allowances and charges on the totals.

Charge reason codes

reason_code of a charge (document level or line level) accepts these 178 codes (ChargeReasonCode, UNCL7161): AA, AAA, AAC, AAD, AAE, AAF, AAH, AAI, AAS, AAT, AAV, AAY, AAZ, ABA, ABB, ABC, ABD, ABF, ABK, ABL, ABN, ABR, ABS, ABT, ABU, ACF, ACG, ACH, ACI, ACJ, ACK, ACL, ACM, ACS, ADC, ADE, ADJ, ADK, ADL, ADM, ADN, ADO, ADP, ADQ, ADR, ADT, ADW, ADY, ADZ, AEA, AEB, AEC, AED, AEF, AEH, AEI, AEJ, AEK, AEL, AEM, AEN, AEO, AEP, AES, AET, AEU, AEV, AEW, AEX, AEY, AEZ, AJ, AU, CA, CAB, CAD, CAE, CAF, CAI, CAJ, CAK, CAL, CAM, CAN, CAO, CAP, CAQ, CAR, CAS, CAT, CAU, CAV, CAW, CAX, CAY, CAZ, CD, CG, CS, CT, DAB, DAC, DAD, DAF, DAG, DAH, DAI, DAJ, DAK, DAL, DAM, DAN, DAO, DAP, DAQ, DL, EG, EP, ER, FAA, FAB, FAC, FC, FH, FI, GAA, HAA, HD, HH, IAA, IAB, ID, IF, IR, IS, KO, L1, LA, LAA, LAB, LF, MAE, MI, ML, NAA, OA, PA, PAA, PC, PL, PRV, RAB, RAC, RAD, RAF, RE, RF, RH, RV, SA, SAA, SAD, SAE, SAI, SG, SH, SM, SU, TAB, TAC, TT, TV, V1, V2, WH, XAA, YY, ZZZ

Tax details

array
Tax breakdown for each rate. Optional. The API stores and returns the entries as you send them. It does not calculate them, and it does not use them for the tax breakdown in the UBL (the API always calculates that breakdown).Each entry has amount (the tax amount, a number or a string) and rate (a string, for example "21.00"). Send rate as a string. A JSON number gives 422: send "rate": "21.00", not "rate": 21. The response gives amount as a string.Example:

Attachments

array
Files in this array are embedded in the UBL. See Attachments and PDF for the permitted file types and for the construct_pdf option.In the response, each attachment has id, file_name, file_type, file_size and file_url. The response does not contain file_data.Example:

Response fields

The response of POST /api/documents/, GET /api/documents/{document_id} and the list endpoints uses the DocumentResponse schema. The request schema is DocumentCreate. The two schemas have almost the same fields. A field with no value is not in the same form in each response:
  • A single-document response does not contain the field. This applies to POST /api/documents/, POST /api/documents/ubl, POST /api/documents/pdf, POST /api/documents/{document_id}/send and GET /api/documents/{document_id}.
  • A list response (GET /api/inbox/, GET /api/outbox/, GET /api/drafts/ and the other document lists) contains the field with the value null.
For example, for a document with no purchase_order, the single-document response has no purchase_order key, and a list entry has "purchase_order": null. Thus, read each optional field as “absent or null”. This table shows the differences between the two schemas: The response-only fields:
string
required
ID of the document.Example: "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
string
required
Date and time of creation (ISO 8601).Example: "2026-10-01T10:00:00Z"
string
required
ID of the attachment, in the form doc-att-....
string | null
URL of the attachment file. The field can be absent or null.

How fields map to UBL

The API converts the JSON document to UBL BIS Billing 3.0. The table shows the conversions that are not self-evident. The response of POST /api/validate/json contains the generated UBL, thus you can examine the result for your own payload. The MIME type of an attachment in the UBL is file_type when it is one of application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx) or application/vnd.oasis.opendocument.spreadsheet (ods). For a different file_type, the API uses the extension of file_name (.pdf, .png, .jpg, .jpeg, .csv, .xlsx, .ods) to find the MIME type. For example, this attachment gets the MIME type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet in the UBL:

Addresses

vendor_address, customer_address and shipping_address are single strings. The API splits vendor_address and customer_address into the parts of a UBL address with these rules. For shipping_address, see Shipping address.
  1. The API splits the string on new lines. If there is only one line, it splits the string on a comma followed by a space (", ").
  2. Part 1 is the street (cbc:StreetName).
  3. Part 2 is the postal code and the city. When the part has the form “postal code, space, city”, the API writes cbc:PostalZone and cbc:CityName. If not, the full part is the city.
  4. The last part is the country (cac:Country/cbc:IdentificationCode) only if it has 2 or 3 letters and no other characters. The API changes it to uppercase.
  5. If the last part is not a country code, the API uses the first two characters of the tax ID of that party. If there is no tax ID, the country is BE.
Use this format, with the ISO 3166-1 alpha-2 country code as the last part:
The first address gives this UBL:
The API does not read a country name as a country. With "..., 1000 Brussels, Belgium", the API ignores Belgium and takes the country from the tax ID prefix, or uses BE. An address in a different country, with a country name and without a tax ID, gets the country BE. Always end the address with the two-letter country code.
In vendor_address and customer_address, do not put a comma followed by a space in the street part (for example "Main Street 1, box 5"). The API reads the text after the comma as the postal code and city. A last part that has only 2 or 3 letters is always read as a country code.
When the vendor or customer address is absent or has no usable parts, the API writes Unknown Street and Unknown City.

Shipping address

The API splits shipping_address by the content of each part, not by the position of the part:
  1. The API splits the string on new lines. If there is only one line, it splits the string on each comma. It removes the spaces around each part and ignores empty parts.
  2. The last part is the country (cbc:IdentificationCode) only if it has exactly 2 letters. The API changes it to uppercase. A part with 3 letters, for example BEL, is not a country code.
  3. The API looks for the last part, after part 1, that starts with a postal code and continues with the city. For example: 3000 Leuven, 1015 CJ Amsterdam or B-1000 Brussels. This part gives cbc:PostalZone and cbc:CityName.
  4. Of the parts before the postal code part, the first is the street (cbc:StreetName). The other parts are the additional street (cbc:AdditionalStreetName). The parts after the postal code part are the region (cbc:CountrySubentity).
  5. When no part has a postal code, part 1 is the street and the last part is the city. The parts between them are the additional street.
  6. When the string has no country code, the API uses the country of the customer. This is the prefix of customer_tax_id, or else the country code at the end of customer_address or billing_address. The API never uses BE as a default for the shipping address.
  7. When the API cannot find a country, it does not write the address to the UBL.
Thus a comma in the street part is permitted in shipping_address. For example, this value:
gives this UBL:
With "shipping_address": "Industrieweg 5, 3000 Leuven" and "customer_tax_id": "BE0848934496", the country is BE from the tax ID. With the same address, no customer_tax_id and no country code in customer_address or billing_address, the UBL has no delivery address. On a received document, the API writes the delivery address to shipping_address as one line, in this sequence: street, additional street, postal code and city, region, country. For example: "Industrieweg 5, Gate 3, 3000 Leuven, BE".

Normalisation and rounding

The API changes some values before it stores the document and generates the UBL. For the fields of line items, allowances and charges, the API rounds a value with more decimals and does not reject it. This rounding is half-even (banker’s rounding): "amount": "10.005" becomes "10.00" and "10.015" becomes "10.02". Send each value with the correct number of decimals. In its calculation of the totals, the API rounds monetary amounts half-up to 2 decimals (0.005 becomes 0.01). The API rounds in this sequence:
  1. Each line amount is rounded.
  2. For each tax group, the API adds the rounded line amounts, subtracts the document-level allowances and adds the document-level charges. A tax group is one combination of tax category and tax rate.
  3. The tax of each group is taxable amount × rate / 100, rounded.
  4. total_tax is the sum of the group taxes.
The API thus calculates VAT for each tax group, not for each line. If you calculate VAT for each line and add the results, your total_tax can be different by some cents. See Invoice totals and calculations.

Example

Complete invoice:
Invoice
Replace the vendor fields with the data of your company. The API rejects a document if the Peppol ID of the vendor is not one of the peppol_ids of your company.

Next Steps

LineItem

Look up the fields of an invoice line.

Create e-invoices

Create and send an invoice with this schema.

Invoice totals and calculations

Calculate the totals that the API checks.

Validation during development

Validate a payload and examine the generated UBL.