Skip to main content

Documentation Index

Fetch the complete documentation index at: https://invopop-mintlify-changelog-week-1778411791.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

Germany requires electronic invoicing for different business scenarios, with two main standards: XRechnung and ZUGFeRD. Both are semantic data models aligned with the European Norm EN 16931 and can be implemented using the same syntaxes.

​
XRechnung

XRechnung is Germany’s official standard for electronic invoices in public procurement (called E-Rechnungen), though it is also used for B2B transactions. It’s part of the implementation of the EU directive 2014/55/EU, which requires all contracting authorities in the EU to accept electronic invoices in a structured XML format. XRechnung can be implemented using two different syntaxes:
  • UN/CEFACT CII (Cross Industry Invoice)
  • OASIS UBL (Universal Business Language)
Both syntaxes contain the same information but have different field names.

​
ZUGFeRD

ZUGFeRD is a German standard for electronic invoicing designed to bridge the gap between traditional invoices and digital formats. ZUGFeRD combines a standard PDF/A-3 invoice with an embedded XML file containing the structured data. This hybrid approach makes it especially popular in B2B transactions, as it allows both people and accounting software to work with the same document. ZUGFeRD is fully aligned with the European Norm EN 16931 and is worth noting that ZUGFeRD and Factur-X are a joint project between Germany and France, and their content is identical.
When referring to syntaxes, it is important to note that XRechnung, ZUGFeRD, and Factur-X are all semantic data models. What this means is that they define the data that must be present in the invoice, but not the actual format of the data or the explicit name of the fields.To implement the semantic models, there are two syntaxes approved by the EU: UN/CEFACT Cross Industry Invoice (CII) and OpenOASIS Universal Business Language (UBL).

​
Prerequisites

To convert invoices to XRechnung or ZUGFeRD format, ensure you have:
  • A valid API key and a basic understanding of the workflow engine and API.
  • An invoice with:
    • Supplier details (company name and required identities). Check the German regime for specifics.
    • Line items with name, price, and applicable taxes.

​
Setup

To issue XRechnung or ZUGFeRD invoices, follow these instructions in the Invopop Console:

​
XRechnung Setup

1

Connect the OASIS UBL app

  1. Navigate to Configuration → Apps.
  2. Locate OASIS UBL in the app discovery list.
  3. Click Connect to activate.
No additional configuration is needed.
2

Configure invoice workflow

XRechnung invoice workflow

This workflow will generate an XRechnung UBL document.

​
ZUGFeRD Setup

1

Connect the UN/CEFACT CII app

  1. Navigate to Configuration → Apps.
  2. Locate UN/CEFACT CII in the app discovery list.
  3. Click Connect to activate.
No additional configuration is needed.
2

Configure invoice workflow

ZUGFeRD invoice workflow

This workflow will generate a ZUGFeRD XML document and embed it into a PDF.

​
Running

Invopop uses the GOBL library to process conversions. GOBL’s implementation validates national business rules in addition to the rules defined in EN 16931-1. Some example invoices are provided below, along with example workflows to send the invoices to. We also recommend using the GOBL Builder to create your own invoices.

​
XRechnung examples

Be sure to set the regime field to DE in your invoices and include the XRechnung addon. This will add extra validations to ensure the document is compliant with the standard.
Standard XRechnung invoice for business-to-business transactions using the UBL format.
{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "DE",
    "$addons": [
        "eu-en16931-v2017",
        "de-xrechnung-v3"
    ],
    "type": "standard",
    "series": "SAMPLE",
    "code": "001",
    "issue_date": "2022-02-01",
    "currency": "EUR",
    "supplier": {
        "name": "Rheinland Technologies GmbH",
        "tax_id": {
            "country": "DE",
            "code": "879558966"
        },
        "inboxes": [
            {
                "key": "peppol",
                "scheme": "9930",
                "code": "DE879558966"
            }
        ],
        "addresses": [
            {
                "num": "27",
                "street": "Friedrichstraße",
                "locality": "Berlin",
                "region": "BE",
                "code": "10117",
                "country": "DE"
            }
        ],
        "people": [
            {
                "name": {
                    "given": "John",
                    "surname": "Doe"
                }
            }  
        ],
        "telephones": [
            {
                "num": "+49100200300"
            }
        ],
        "emails": [
            {
                "addr": "billing@example.com"
            }
        ]
    },
    "customer": {
        "name": "Bavaria Solutions GmbH",
        "tax_id": {
            "country": "DE",
            "code": "993930191"
        },
        "inboxes": [
            {
                "key": "peppol",
                "scheme": "9930",
                "code": "DE993930191"
            }
        ],
        "addresses": [
            {
                "num": "15",
                "street": "Marienplatz",
                "locality": "München",
                "region": "BY",
                "code": "80331",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "test@example.com"
            }
        ]
    },
    "lines": [
        {
            "quantity": "20",
            "item": {
                "name": "Development services",
                "price": "90.00",
                "unit": "h"
            },
            "sum": "1800.00",
            "discounts": [
                {
                    "reason": "Special discount",
                    "percent": "10%",
                    "amount": "180.00"
                }
            ],
            "taxes": [
                {
                    "cat": "VAT",
                    "rate": "general"
                }
            ],
            "total": "1620.00"
        }
    ],
    "ordering": {
        "code": "N"
    },
    "payment": {
        "terms": {
            "notes": "Will be paid by 2026-06-02"
        },
        "instructions": {
            "key": "credit-transfer+sepa",
            "credit_transfer": [
                {
                    "iban": "DE89370400440532013000",
                    "name": "Random Bank Co."
                }
            ]
        }
    }
}
In your invoice data, make sure to include the XRechnung addon and set the regime as DE.

​
ZUGFeRD examples

Be sure to set the regime field to DE in your invoices and include the ZUGFeRD addon. This will add extra validations to ensure the document is compliant with the standard.
Standard ZUGFeRD invoice for business-to-consumer transactions with embedded XML in PDF format.
{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "DE",
    "$addons": [
        "eu-en16931-v2017",
        "de-zugferd-v2"
    ],
    "$tags": [
        "simplified"
    ],
    "uuid": "3aea7b56-59d8-4beb-90bd-f8f280d852a0",
    "type": "standard",
    "series": "SAMPLE",
    "code": "001",
    "issue_date": "2022-02-01",
    "currency": "EUR",
    "supplier": {
        "name": "Provide One GmbH",
        "tax_id": {
            "country": "DE"
        },
        "addresses": [
            {
                "num": "16",
                "street": "Dietmar-Hopp-Allee",
                "locality": "Walldorf",
                "code": "69190",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "billing@example.com"
            }
        ]
    },
    "lines": [
        {
            "quantity": "20",
            "item": {
                "name": "Development services",
                "price": "90.00",
                "unit": "h"
            },
            "sum": "1800.00",
            "discounts": [
                {
                    "reason": "Special discount",
                    "percent": "10%",
                    "amount": "180.00"
                }
            ],
            "taxes": [
                {
                    "cat": "VAT",
                    "rate": "general"
                }
            ],
            "total": "1620.00"
        }
    ],
    "payment": {
        "advances": [
            {
                "description": "Paid in full",
                "percent": "100%",
                "amount": "1927.80"
            }
        ],
        "instructions": {
            "key": "card"
        }
    }
}
Comprehensive ZUGFeRD invoice demonstrating additional optional fields such as ordering information, payment terms, delivery details, and discounts.
{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "DE",
    "$addons": [
        "eu-en16931-v2017",
        "de-zugferd-v2"
    ],
    "type": "standard",
    "series": "SAMPLE",
    "code": "001",
    "issue_date": "2024-02-13",
    "currency": "EUR",
    "tax": {
        "ext": {
            "untdid-document-type": "380"
        }
    },
    "supplier": {
        "name": "Provide One GmbH",
        "tax_id": {
            "country": "DE",
            "code": "111111125"
        },
        "people": [
            {
                "name": {
                    "given": "John",
                    "surname": "Doe"
                }
            }
        ],
        "addresses": [
            {
                "num": "16",
                "street": "Dietmar-Hopp-Allee",
                "locality": "Walldorf",
                "code": "69190",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "billing@example.com"
            }
        ],
        "telephones": [
            {
                "num": "+49100200300"
            }
        ]
    },
    "customer": {
        "name": "Sample Consumer",
        "tax_id": {
            "country": "DE",
            "code": "282741168"
        },
        "addresses": [
            {
                "num": "25",
                "street": "Werner-Heisenberg-Allee",
                "locality": "München",
                "code": "80939",
                "country": "DE"
            }
        ],
        "emails": [
            {
                "addr": "email@sample.com"
            }
        ]
    },
    "lines": [
        {
            "quantity": "20",
            "item": {
                "name": "Development services",
                "price": "90.00",
                "unit": "h"
            },
            "taxes": [
                {
                    "cat": "VAT",
                    "key": "standard",
                    "rate": "general",
                    "percent": "19%",
                    "ext": {
                        "untdid-tax-category": "S"
                    }
                }
            ]
        }
    ],
    "discounts": [
        {
            "reason": "Promotion discount",
            "amount": "10.00",
            "taxes": [
                {
                    "cat": "VAT",
                    "key": "standard",
                    "rate": "general",
                    "percent": "19%",
                    "ext": {
                        "untdid-tax-category": "S"
                    }
                }
            ],
            "ext": {
                "untdid-allowance": "88"
            }
        }
    ],
    "charges": [
        {
            "reason": "Freight",
            "amount": "11.00",
            "taxes": [
                {
                    "cat": "VAT",
                    "key": "standard",
                    "rate": "general",
                    "percent": "19%",
                    "ext": {
                        "untdid-tax-category": "S"
                    }
                }
            ]
        }
    ],
    "ordering": {
        "code": "PO4711",
        "period": {
            "start": "2013-03-10",
            "end": "2013-04-10"
        },
        "contracts": [
            {
                "code": "2013-05"
            }
        ],
        "receiving": [
            {
                "code": "3544"
            }
        ],
        "despatch": [
            {
                "code": "5433"
            }
        ]
    },
    "payment": {
        "payee": {
            "name": "Ebeneser Scrooge AS",
            "identities": [
                {
                    "label": "CompanyID",
                    "code": "989823401"
                },
                {
                    "label": "0088",
                    "code": "2298740918237"
                }
            ]
        },
        "terms": {
            "due_dates": [
                {
                    "date": "2013-07-20",
                    "percent": "100%"
                }
            ],
            "notes": "2 % discount if paid within 2 days\n            Penalty percentage 10% from due date"
        },
        "instructions": {
            "key": "credit-transfer",
            "ref": "0003434323213231",
            "credit_transfer": [
                {
                    "iban": "NO9386011117947",
                    "bic": "DNBANOKK"
                }
            ],
            "card": {
                "last4": "1234",
                "holder": "John Doe"
            },
            "direct_debit": {
                "ref": "1234567890",
                "creditor": "987654321",
                "account": "DE89370400440532013000"
            },
            "ext": {
                "untdid-payment-means": "30"
            }
        }
    },
    "delivery": {
        "receiver": {
            "addresses": [
                {
                    "street": "Deliverystreet 2",
                    "street_extra": "Side door",
                    "locality": "DeliveryCity",
                    "region": "RegionD",
                    "code": "523427",
                    "country": "NO"
                }
            ]
        },
        "identities": [
            {
                "label": "0088",
                "code": "6754238987643"
            }
        ],
        "date": "2024-02-10"
    }
}
In your invoice data, make sure to include the ZUGFeRD addon and set the regime as DE.

​
FAQ

Pick a format based on the recipient: XRechnung (UBL or CII) for B2G via Peppol, ZUGFeRD/Factur-X for B2B where a human-readable PDF is also wanted. Both are EN 16931-compliant — Invopop generates either from the same GOBL invoice.
Generate a GOBL invoice with the de-xrechnung-v3 addon, then run the Peppol Send workflow. Invopop emits XRechnung (UBL or CII per recipient preference), looks up the recipient’s Access Point, and delivers via Peppol.
Both syntaxes are equally valid and contain the same information, so in the majority of cases the choice has no consequences.If you plan on sending invoices through the PEPPOL network, we recommend using UBL as it is the supported format. If you plan on also issuing invoices in ZUGFeRD or Factur-X, it might be more convenient to use CII, as it is the syntax also supported by ZUGFeRD and Factur-X.
For ZUGFeRD PDFs, the XML file is embedded within the PDF itself. To extract and view it, you can use the Attachments section in Adobe Acrobat Reader.Alternatively, you can use specialized tools like the SysTools PDF Extractor to extract the XML file.
See the Germany tax regime in GOBL for tax categories and identifiers. The XRechnung mapping lives in de-xrechnung-v3; ZUGFeRD/Factur-X share the EN 16931 CII profile.
In countries where Peppol is the standard but not mandatory, you may still need to issue an e-invoice when the recipient isn’t on the network. Both parties can agree on an alternative transfer method, but the invoice must still be EN16931 compliant.Recommended approach:
  • Set up a separate workflow that generates the XML without the send-Peppol-document step
  • Or reuse your existing workflow without the customer Peppol ID — the send step is automatically skipped
  • Fetch the generated XML and deliver it through the agreed channel, typically email
B2C invoices typically lack the structured customer information required for Peppol delivery, and most consumers don’t have inboxes. Use a conditional workflow:
  1. Add an If/Else step that checks for a customer inbox using count(customer.inboxes, true) > 0.
  2. On the false branch, generate a PDF and email it to the customer, then stop the flow.
This routes B2B invoices through Peppol while keeping a smooth path for consumers.
If a job fails with KO and receiver not found in the peppol network, treat it like an invalid email address — the recipient simply isn’t reachable on Peppol. Add the Lookup Participant ID step (ideally in a separate validation workflow run against customer data) so you catch missing IDs before generating the invoice.
No. The regime is automatically derived from the supplier’s settings, which is the recommended approach for Peppol — leave it unset on the document.
See the oasis-ubl-v2 addon and the Peppol app reference for required fields, supported document types, and Participant ID schemes.
More available in our Germany FAQ section

Participate in our community

Ask and answer questions about invoicing in Germany →