Example Documents

Relevant source files

• test/data/convert/peppol/out/invoice-with-contract-ref.xml
• test/data/parse/discount-taxes.xml
• test/data/parse/en16931/out/credit-note1.json
• test/data/parse/en16931/out/custom-namespace-prefixes.json
• test/data/parse/en16931/out/ubl-example5.json
• test/data/parse/france-cius/out/b2b-reg.json
• test/data/parse/peppol/out/Allowance-example.json
• test/data/parse/peppol/out/Vat-category-S.json
• test/data/parse/peppol/out/base-creditnote-correction.json
• test/data/parse/peppol/out/base-example.json
• test/data/parse/peppol/out/invoice-peppol.json
• test/data/parse/peppol/out/nbio-stuck-ubl.json
• test/data/parse/peppol/out/vat-category-E.json

This page presents real-world example invoices that demonstrate the capabilities of the gobl.ubl conversion system. These examples are located in the test data directory and serve both as test fixtures and documentation of supported features. For information about the test framework that uses these examples, see Test Framework. For details about specific document types and tags, see Document Types and Tags.

Test Data Organization

The example documents are organized in two main categories based on conversion direction:

Sources: test/data/parse/out/ubl-example1.json1-578 test/data/parse/out/ubl-example4.json1-252 test/data/parse/out/base-example.json1-285

The parse/ directory contains UBL XML documents and their expected GOBL JSON output after parsing. The convert/ directory contains GOBL JSON documents and their expected UBL XML output after conversion.

Example Feature Matrix

The following table categorizes example documents by the features they demonstrate:

Example File	Profile	Tax Rates	Charges	Advances	Delivery	Credit Note	Notes
ubl-example1.json	EN16931	2 (6%, 21%)	No	No	No	No	Large item list (20 lines)
ubl-example3.json	EN16931	2 (25%, 10%)	Yes	No	No	No	Document-level charges
ubl-example4.json	EN16931	2 (25%, 12%)	No	No	Yes	No	Multi-rate with delivery
ubl-example6.json	EN16931	2 (25%, 12%)	No	No	No	No	Minimal supplier/customer
ubl-example7.json	EN16931	1 (Outside scope)	No	No	No	No	Non-VAT taxation
ubl-example8.json	EN16931	1 (21%)	No	No	Yes	No	Utility invoice with metadata
ubl-example9.json	EN16931	1 (21%)	No	No	No	No	Subscription service
base-example.json	EN16931	1 (25%)	Yes	No	Yes	No	Full featured standard
base-creditnote-correction.json	EN16931	1 (25%)	Yes	No	Yes	Yes	Credit note with preceding
base-negative-inv-correction.json	EN16931	1 (25%)	Yes	No	Yes	No	Negative correction invoice
sales-order-example.json	EN16931	1 (25%)	Yes	No	Yes	No	With purchase order
invoice-peppol.json	Peppol	1 (25%)	Yes	No	No	No	Peppol routing identifiers
credit-note1.json	None	0 (No tax)	No	No	No	Yes	Simple credit note
vat-category-E.json	EN16931	1 (0% exempt)	No	No	No	No	VAT exemption
vat-category-O.json	EN16931	1 (Outside scope)	No	No	No	No	Non-EU VAT treatment

Sources: test/data/parse/out/ubl-example1.json1-578 test/data/parse/out/ubl-example3.json1-227 test/data/parse/out/ubl-example4.json1-252 test/data/parse/out/sales-order-example.json1-290 test/data/parse/out/invoice-peppol.json1-267

Standard Invoice Structure

A typical standard invoice example demonstrates the complete invoice structure with all major components:

Sources: test/data/parse/out/base-example.json1-285

This example (base-example.json) demonstrates:

• Complete party information with tax IDs and legal identities
• Multiple line items including negative quantities (returns/adjustments)
• Document-level charges with tax calculation
• Payment terms with due dates and credit transfer instructions
• Delivery information with receiver address
• Standard 25% VAT rate calculation

Credit Note Examples

Credit notes use the credit-note type and reference preceding invoices:

Sources: test/data/parse/out/base-creditnote-correction.json1-288

Key characteristics of credit notes:

• type field set to "credit-note" at test/data/parse/out/base-creditnote-correction.json17
• preceding array references the original invoice at test/data/parse/out/base-creditnote-correction.json21-24
• UN/TDID document type code 381 in tax extensions at test/data/parse/out/base-creditnote-correction.json29
• Line items typically match the original invoice being credited
• Optional notes explaining the credit reason at test/data/parse/out/base-creditnote-correction.json282-286

Negative Invoice Corrections

An alternative to credit notes is using a standard invoice with negative line items:

Sources: test/data/parse/out/base-negative-inv-correction.json1-290

Negative invoice corrections:

• Use type: "standard" instead of "credit-note" at test/data/parse/out/base-negative-inv-correction.json17
• UN/TDID document type remains 380 (invoice) at test/data/parse/out/base-negative-inv-correction.json29
• Line quantities are negated at test/data/parse/out/base-negative-inv-correction.json122
• Charges become negative at test/data/parse/out/base-negative-inv-correction.json198
• All totals are negative at test/data/parse/out/base-negative-inv-correction.json261-287
• Still references preceding invoice at test/data/parse/out/base-negative-inv-correction.json21-24

Multiple Tax Rates Example

Many jurisdictions apply different VAT rates to different product categories. Example ubl-example1.json demonstrates this:

Sources: test/data/parse/out/ubl-example1.json71-511 test/data/parse/out/ubl-example1.json536-571

The tax breakdown at test/data/parse/out/ubl-example1.json539-567 shows:

• Two different VAT rates applied: 6% and 21%
• Each rate has its own base amount and calculated tax
• Total tax is the sum of all rate amounts: 24.19 + 9.74 = 33.93
• Each line item specifies its tax category and rate at the line level

Invoices with Document-Level Charges

Document-level charges (or allowances) apply to the entire invoice rather than individual lines:

Sources: test/data/parse/out/ubl-example3.json133-148 test/data/parse/out/ubl-example3.json184-219

The charges structure at test/data/parse/out/ubl-example3.json133-148 shows:

• Index (i) to order charges
• Human-readable reason field
• amount field for the charge value
• taxes array specifying the applicable tax rate
• The charge amount (100.00) is added to the line items sum (3200.00) to get the total (3300.00)
• Taxes are calculated on the sum of lines + charges: (1600.00 + 100.00) × 25% + 1600.00 × 10%

Peppol Profile Example

Peppol invoices include routing identifiers and follow the Peppol BIS Billing 3.0 specification:

Sources: test/data/parse/out/invoice-peppol.json12-14 test/data/parse/out/invoice-peppol.json43-46 test/data/parse/out/invoice-peppol.json72-76

Peppol-specific features:

• inboxes array with Peppol participant identifiers at test/data/parse/out/invoice-peppol.json43-46
• Scheme identifiers (0151, 0007) used for routing
• ISO scheme ID extensions on identities at test/data/parse/out/invoice-peppol.json37-39
• EN16931 addon requirement at test/data/parse/out/invoice-peppol.json13-14
• Full party identification including legal IDs and tax IDs

Delivery Information Example

Delivery details include receiver information, addresses, and dates:

Sources: test/data/parse/out/ubl-example4.json197-209

The delivery structure at test/data/parse/out/ubl-example4.json197-209 includes:

• receiver party with address information
• Delivery date separate from invoice issue date
• Full address components (street, locality, code, country)
• Can include receiver party identifiers if different from customer

Payment Terms and Instructions

Payment information includes terms, due dates, and detailed instructions:

Sources: test/data/parse/out/ubl-example4.json174-196

Payment components:

• terms with due_dates array at test/data/parse/out/ubl-example4.json175-183
• Each due date specifies date, amount, and percentage
• instructions with payment method key at test/data/parse/out/ubl-example4.json184-195
• credit_transfer array for bank details at test/data/parse/out/ubl-example4.json187-190
• UN/TDID payment means code in extensions at test/data/parse/out/ubl-example4.json192-194

Utility Invoice with Line Metadata

Utility invoices often include additional metadata on line items:

Sources: test/data/parse/out/ubl-example8.json71-96

Line item metadata at test/data/parse/out/ubl-example8.json78-83 includes:

• Custom fields stored in item.meta map
• Key-value pairs for domain-specific data
• In this example: contract terms, correction factors, network levels
• Metadata preserved during conversion but not validated

Special VAT Categories

Some transactions use special VAT treatment categories:

Zero-Rated (Category Z)

Sources: test/data/parse/out/vat-category-E.json91-99 test/data/parse/out/vat-category-E.json132-140

Outside Scope (Category O)

Sources: test/data/parse/out/vat-category-O.json80-86 test/data/parse/out/vat-category-O.json119-127

Special VAT categories:

• Zero-rated (Z): 0% rate but still within VAT scope at test/data/parse/out/vat-category-E.json94-95
• Outside scope (O): Not subject to VAT at all at test/data/parse/out/vat-category-O.json83-85
• Exempt (E): Exempt from VAT (not shown in provided examples)
• UN/TDID tax category codes stored in extensions

Ordering and Contract References

Orders and contracts link invoices to business agreements:

Sources: test/data/parse/out/sales-order-example.json206-212 test/data/parse/out/sales-order-example.json118

Ordering structures:

• Document-level ordering.code at test/data/parse/out/sales-order-example.json207
• purchases array with purchase order references at test/data/parse/out/sales-order-example.json208-211
• Line-level order field at test/data/parse/out/sales-order-example.json118
• contracts array for contract references (see test/data/parse/out/ubl-example9.json100-104)
• period for contract or billing periods (see test/data/parse/out/ubl-example8.json318-322)

Line Item Details

Line items include comprehensive product and pricing information:

Sources: test/data/parse/out/sales-order-example.json115-150

Complete line item structure:

• Index i for ordering at test/data/parse/out/sales-order-example.json116
• quantity and order (purchase order line ref) at test/data/parse/out/sales-order-example.json117-118
• cost for accounting strings at test/data/parse/out/sales-order-example.json119
• item with name, identities, description at test/data/parse/out/sales-order-example.json120-137
• identities with ISO scheme IDs at test/data/parse/out/sales-order-example.json122-132
• price, unit, origin at test/data/parse/out/sales-order-example.json135-137
• Calculated sum and total at test/data/parse/out/sales-order-example.json139-150

Complete Invoice Example Walkthrough

Let's examine ubl-example4.json as a comprehensive example demonstrating multiple features:

Document Header

• Issue date: 2013-04-10 at test/data/parse/out/ubl-example4.json18
• Currency: DKK at test/data/parse/out/ubl-example4.json19
• Invoice code: TOSL110 at test/data/parse/out/ubl-example4.json17

Parties

• Supplier: SellerCompany with Danish VAT ID at test/data/parse/out/ubl-example4.json26-70
• Customer: Buyercompany ltd at test/data/parse/out/ubl-example4.json71-96
• Both parties have full contact details (addresses, emails, phones)

Line Items (3 items)

1. Printing paper: 1000 × 1.00 = 1000.00 @ 25% VAT at test/data/parse/out/ubl-example4.json97-120
2. Parker Pen: 100 × 5.00 = 500.00 @ 25% VAT at test/data/parse/out/ubl-example4.json121-143
3. American Cookies: 500 × 5.00 = 2500.00 @ 12% VAT at test/data/parse/out/ubl-example4.json144-165

Ordering

• Purchase order reference: 123 at test/data/parse/out/ubl-example4.json167-173

Payment

• Due date: 2013-05-10 at test/data/parse/out/ubl-example4.json177
• Method: Credit transfer (code 30) at test/data/parse/out/ubl-example4.json185
• IBAN: DK1212341234123412 at test/data/parse/out/ubl-example4.json189
• Payment reference: Payref1 at test/data/parse/out/ubl-example4.json186

Delivery

• Address: Deliverystreet, Deliverycity 9000, DK at test/data/parse/out/ubl-example4.json198-207
• Date: 2013-04-15 at test/data/parse/out/ubl-example4.json208

Financial Totals

• Line items sum: 4000.00 at test/data/parse/out/ubl-example4.json211
• Tax breakdown at test/data/parse/out/ubl-example4.json213-241:
  • 1500.00 @ 25% = 375.00
  • 2500.00 @ 12% = 300.00
  • Total tax: 675.00
• Payable amount: 4675.00 at test/data/parse/out/ubl-example4.json244

Notes

• Free text note at test/data/parse/out/ubl-example4.json246-250

Sources: test/data/parse/out/ubl-example4.json1-252

This example demonstrates: multiple tax rates, purchase order references, payment instructions, delivery information, party contact details, and financial calculations.