Generate XRechnung invoices for German public buyers

01What XRechnung is

XRechnung is a specification of EN 16931, the European e-invoice standard. It is published by KoSIT, the coordination office for IT standards of the German federal states. It adds German business rules on top of the European ones, such as a mandatory buyer reference and contact details for the seller.

An XRechnung has no visual layout. The XML file is the invoice. Public portals, such as the federal ZRE and OZG-RE portals, read it directly. Many German businesses accept XRechnung too, because it is a valid e-invoice under the 2025 rules.

Both syntaxes carry exactly the same data, and the validators treat them alike. Ask the public buyer which one their portal takes. If they do not mind, UBL is the common choice for portals and Peppol, and CII matches your ZUGFeRD files.

02The fields XRechnung adds

An XRechnung needs everything a normal EN 16931 invoice has, plus these fields. The API checks them all at once and lists every one that is missing.

• buyer_reference: the Leitweg-ID the public buyer gave you, such as 04011000-12345-67.
• seller.contact with a name, a phone number and an email address.
• seller.electronic_address and buyer.electronic_address; for a public buyer usually the Leitweg-ID with scheme 0204.
• Payment details, such as an IBAN for a bank transfer, and a due date or payment terms.

The Leitweg-ID tells the portal which office receives the invoice. If you do not have it, ask the buyer before you send anything; a portal rejects an invoice without it.

03One request for an XRechnung

{
  "e_invoice": {
    "standard": "xrechnung-ubl",
    "invoice": {
      "number": "RE-2026-0817",
      "issue_date": "2026-10-11",
      "currency": "EUR",
      "buyer_reference": "04011000-12345-67",
      "seller": {
        "name": "Lindqvist Software GmbH",
        "vat_id": "DE123456789",
        "electronic_address": { "value": "[email protected]", "scheme": "EM" },
        "address": { "line1": "Kastanienallee 12", "city": "Berlin", "postal_code": "10435", "country_code": "DE" },
        "contact": { "name": "Accounts", "phone": "+49 30 1234567", "email": "[email protected]" }
      },
      "buyer": {
        "name": "Bezirksamt Hamburg-Mitte",
        "electronic_address": { "value": "04011000-12345-67", "scheme": "0204" },
        "address": { "line1": "Caffamacherreihe 1", "city": "Hamburg", "postal_code": "20355", "country_code": "DE" }
      },
      "payment": { "iban": "DE89370400440532013000", "due_date": "2026-11-10" },
      "lines": [
        { "name": "Licence for the permit portal, 2027", "quantity": 1, "unit_price": "12000.00", "vat": { "category": "S", "rate": 19 } },
        { "name": "Onboarding workshop", "quantity": 2, "unit_code": "DAY", "unit_price": "1100.00", "vat": { "category": "S", "rate": 19 } }
      ]
    }
  },
  "response": "url"
}

{
  "id": "6b2e4c1a-9f3d-4e7b-8a15-2c9d0e1f3a47",
  "status": "succeeded",
  "pages": 0,
  "bytes": 6214,
  "url": "https://api.castpdf.com/v1/files/6b2e4c1a-9f3d-4e7b-8a15-2c9d0e1f3a47?exp=1793952000&sig=…",
  "expires_at": "2026-11-10T09:30:00.000Z",
  "blocked_resources": [],
  "warnings": [],
  "e_invoice": { "standard": "xrechnung-ubl", "profile": "xrechnung", "xml_filename": "xrechnung.xml" }
}

Without "response": "url" the reply body is the XML itself, application/xml, named after the invoice number. Upload it to the buyer’s portal, or send it the way the buyer asked for.

04When something is missing

A portal that rejects an invoice usually tells you one rule at a time. The API tells you everything at once, before an XML exists. Each problem has the field path and a plain sentence about how to fix it.

1. YouSend an XRechnung request without buyer_reference.
2. CastPDF400 invalid_e_invoice: e_invoice.invoice.buyer_reference is required for XRechnung.
3. YouAdd the Leitweg-ID and send the same request again.
4. CastPDF200 with the XRechnung XML. One document counted.

A rejected request is never counted. Show the messages to whoever keeps the invoice data, or map each path back to a field in your own form.

05Who needs XRechnung

• Suppliers to public bodies: federal ministries, states, cities and public companies. Most of them take invoices only through a portal, as XRechnung.
• Software companies that bill public schools, hospitals or universities for licences and support every year.
• Businesses whose German customers ask for it, because their accounting software reads XRechnung directly.

CastPDF creates the XML. It does not upload it to a portal or send it over Peppol. Most portals offer a web upload for single invoices, and many public buyers also accept email. Ask the buyer which channel they expect.

06How our XRechnung output was checked

Every XRechnung our test suite generates, in CII and UBL, passes the official XSD and the KoSIT XRechnung 3.0.2 Schematron rules. On 10 October 2026 we also ran the KoSIT validator 1.6.3, the reference tool for XRechnung. It accepted all 14 files we gave it, with no failed assertions.

That covers six invoice shapes, including a credit note as a UBL CreditNote, reverse charge, an exempt sale and an intra-EU supply. It does not replace a test with the buyer’s portal, which may check things no validator sees, such as whether the Leitweg-ID exists.

07Common questions

08More use cases

• Use caseZUGFeRDReadable PDF/A-3b invoices with the EN 16931 XML inside, for German businesses.
• Use caseFactur-XFactur-X PDF/A-3 invoices for the French reform, from one JSON request.
• Use caseReceipt PDF generatorA till-style receipt with VAT and a paid stamp, sent the moment a payment clears.
• Use caseReport PDF generatorWeekly, monthly or board reports built from raw figures, with headers and page numbers on every page.
• Use caseTicket PDF generatorOne printable ticket per booking, with the guest name, booking code and seating details.