E-invoicing: Germany (XRechnung, ZUGFeRD) for Magento 2: User Guide

Create German e-invoices ("E-Rechnung") from your Magento invoices and credit memos: ZUGFeRD hybrid PDFs for businesses and XRechnung 3.0 for public bodies with a Leitweg-ID. Every document is checked against the EN 16931 and XRechnung rules before it is sent, stored unchangeable with an audit trail, attached to Magento's invoice e-mail or sent over Peppol, and offered for download in the customer account.

This package adds the German formats to E-Invoicing Core (commercegears/module-e-invoicing-core, free), which provides the queue, the admin grid, the document page, validation, delivery and the checkout fields.

• Storefront demo (checkout with VAT ID and Leitweg-ID, then the demo customer's e-invoices; the guided tour signs you in): https://demo.commercegears.com/driven-backpack.html and on Hyvä https://demo.commercegears.com/hyva/driven-backpack.html
• Admin demo: https://demo.commercegears.com/try-admin/e-invoicing-de
• Changelog: Release notes · Questions: FAQ

Background: receiving e-invoices has been mandatory for German businesses since 1 January 2025. Issuing them is required from 1 January 2027 for businesses with a prior-year turnover above EUR 800,000 and from 1 January 2028 for everyone. Check your own obligations with your tax adviser.

1. Requirements

No account or credentials are needed for ZUGFeRD by e-mail or for XRechnung downloads.

2. Installation

With Composer. Use the Composer keys from your account on commercegears.com (see https://commercegears.com/composer-access/):

composer config repositories.commercegears composer https://repo.commercegears.com
composer config --auth http-basic.repo.commercegears.com PUBLIC_KEY PRIVATE_KEY
composer require commercegears/module-e-invoicing-de
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

E-Invoicing Core is installed with it. Magento's cron must run, because documents are generated and sent by the cron job every 5 minutes.

3. Quick start

1. Stores > Configuration > CommerceGears > E-Invoicing > General > Enabled = Yes (default No).
2. Fill in Seller (Your Company): legal name, VAT ID or tax number, street, postcode, city, country Germany, contact name, phone and e-mail, and your IBAN (and BIC) for invoices paid later.
3. Leave Countries, Formats and Delivery as it is to use the suggested rules (see section 5).
4. Click Save Config.
5. Invoice an order of a German business customer. Within 5 minutes the ZUGFeRD document appears under CommerceGears > E-Invoicing > E-Invoices; when Magento sends the invoice e-mail, the ZUGFeRD PDF is attached.

4. Formats

The ZUGFeRD PDF is what your customers open. By default it uses the German invoice layout: an invoice ("Rechnung") or credit note ("Rechnungskorrektur") in German with small English sub-labels, drawn from the same data as the embedded XML, so the readable PDF and the XML cannot differ. It shows the details required by § 14 UStG: seller name, address and VAT ID or tax number, buyer name, address and VAT ID, invoice number and date, date of supply, items with quantity, unit price and VAT rate, net amounts and VAT per rate, the notes for reverse charge ("Steuerschuldnerschaft des Leistungsempfängers"), intra-Community supplies and exports, payment terms, due date and bank details, the Leitweg-ID for public bodies, the original invoice for credit notes, your company details in the footer and a note that the file is a ZUGFeRD e-invoice. Your PDF logo is printed when set. You can switch to Magento's own invoice PDF instead (section 6), for example if a PDF module styles your invoices.

MINIMUM and BASIC WL profiles are not offered, because they are not e-invoices under German rules. In our tests the XML files were validated with the official KoSIT validator (XRechnung 3.0.2 configuration: UBL invoice, UBL credit note, CII, EN 16931 CII) and the ZUGFeRD PDFs with Mustang (ZUGFeRD rules) and veraPDF (PDF/A-3B).

5. Businesses, public bodies and the Leitweg-ID

Suggested rules (used until you save your own rules):

Public bodies are recognised by their Leitweg-ID: a German buyer whose order reference is a Leitweg-ID (coarse address, optional fine address, two check digits, for example 04011000-1234512345-06) counts as a public body. The check digits must match (ISO 7064 MOD 97-10, as in the KoSIT format specification), so a purchase order number that only looks like one, such as 2026-15, does not make the buyer a public body.

German VAT IDs entered at checkout, on the order page or through the REST API are checked: DE followed by 9 digits with a matching check digit. A typing error is shown to the buyer at once instead of ending up on the e-invoice. At checkout the reference field is labelled "Leitweg-ID or your order reference" for German addresses, with the note "Public authorities: please enter your Leitweg-ID."

Buyer reference (BT-10) is always filled, as XRechnung requires: the Leitweg-ID, otherwise the buyer's purchase order number, otherwise the Magento order number.

Over Peppol, a public body without its own Peppol ID is addressed with the Leitweg-ID as Peppol ID (scheme 0204). Without the Peppol package, download the XRechnung and upload it to the buyer's portal.

6. Configuration

All settings are in Stores > Configuration > CommerceGears > E-Invoicing (section commercegears_einvoicing, provided by E-Invoicing Core). Most can be set per website or store view.

General

• Enabled: when No, no e-invoices are created or sent and no fields are shown at checkout. Default: No.
• Create E-Credit Notes for Credit Memos: credit notes refer to the original invoice. Default: Yes.
• Send Automatically: valid documents go through their network by cron. E-mail documents always go with Magento's invoice e-mail. Default: Yes.
• Default Unit Code (default C62) and Product Attribute with the Unit Code (optional).
• Purchase Order Number Field (Checkout Fields): if CommerceGears Checkout Fields is installed, the field whose value is written as the order reference. Default: po_number.

Seller (Your Company): legal name, trading name, VAT ID, tax number, tax office, company registration number, address, contact name, phone and e-mail, electronic address scheme and ID, IBAN, BIC, account holder and an invoice note. XRechnung needs the contact name, phone and e-mail (BR-DE-2), the VAT ID or tax number (BR-DE-16) and, for credit transfers, the IBAN (BR-DE-19, BR-DE-23). Your contact e-mail is used as your electronic address (scheme EM) when no electronic address ID is set. Empty fields fall back to Magento's store information.

Countries, Formats and Delivery: rules of your country, the buyer's country and the buyer type (businesses, public bodies, consumers, all) with a format and a delivery. The most specific rule wins; no matching rule, no e-invoice. Saving an empty table brings back the suggested rules; to stop e-invoicing set Enabled = No.

Payment Terms: payment methods paid later (default bank transfer, check / money order, cash on delivery, purchase order), days until payment is due (default 14) and the terms text. Paid invoices are marked as paid.

VAT Categories: detection of intra-EU and export sales, the category for 0 % to EU businesses (K or AE), the category for other 0 % items and a mapping per product tax class.

Checkout: Ask for E-Invoice Details (default Yes) shows the business purchase checkbox and the fields at the payment step.

E-mail and Customer Account: Attach All E-Invoices to Invoice E-mails (default No: only documents with delivery "E-mail") and Download in Customer Account (default Yes).

Validation: External Validator URL of your own KoSIT validator and Use It for Every New Document (default No). See section 9.

Advanced: documents per cron run (50), send attempts (6) and how long API call details are kept (90 days).

E-Invoicing: Germany > ZUGFeRD PDF (section commercegears_einvoicing_de, per store view):

• PDF Layout: German invoice layout (made from the e-invoice data) (default) or Magento's invoice PDF. Applies to documents created from then on; documents already created keep their file. Stores that created ZUGFeRD documents before version 2.2.0 keep Magento's invoice PDF after the update until you switch.
• Show PDF Logo: prints the logo from Sales > Sales > Invoice and Packing Slip Design (PNG or JPEG); without a logo your company name is printed. Default: Yes.

7. Daily use

At checkout (Luma checkout, also used by Hyvä stores): at the payment step, buyers tick "This is a business purchase (electronic invoice)" and enter their VAT ID (when Magento's own VAT field is hidden) and the Leitweg-ID or order reference. All fields are optional, checked on the server and copied to the order. Company name and address come from the billing address.

E-Invoices grid (CommerceGears > E-Invoicing > E-Invoices): every document with type, number, order, buyer, country, total, format, delivery, status and problem. Full-text search, filters and the mass actions Generate / Regenerate (Not Sent Yet), Send, Check Delivery Status, Cancel (Not Sent Yet) and Download Files (ZIP).

Document page: summary (status, buyer and electronic address, format, delivery, network ID, SHA-256 checksums), validation result with rule IDs and the audit trail. Depending on the state: Download XML, Download PDF, Regenerate, Send E-mail to Customer, Validate Again and Cancel.

Order page (Sales > Orders, Information tab): the E-Invoicing box lists the order's documents with their files, creates an e-invoice by hand (Create E-Invoice, any installed format and delivery) and edits the Buyer E-Invoice Details (business purchase, VAT ID, Leitweg-ID or order reference). After a change, regenerate documents that were not sent yet.

Customer account: logged-in customers see Electronic Invoices with Download PDF and Download XML on the Invoices and Refunds tabs of their orders, on Luma and Hyvä. Each download is recorded in the audit trail.

Once sent, a document cannot be changed. Files are written once and checked against their checksum on every read; a sent document cannot be regenerated or cancelled. Issue a credit memo instead.

8. CLI

bin/magento commercegears:einvoice:process                                  # what the cron does
bin/magento commercegears:einvoice:generate invoice 000000123               # by invoice number (routing rules)
bin/magento commercegears:einvoice:generate invoice 000000123 --format=xrechnung_cii
bin/magento commercegears:einvoice:generate document 42                     # regenerate (not sent yet)
bin/magento commercegears:einvoice:send 42 [--status]                       # send or check status
bin/magento commercegears:einvoice:validate 42 [--external]                 # checksum, XSD, your validator
bin/magento commercegears:einvoice:validate /path/invoice.pdf               # check a ZUGFeRD PDF or an XML file

9. Validation and the KoSIT validator

Every document is checked with the built-in EN 16931 rules, the XRechnung rules that can be checked on the data, the XML schema (shipped with the module, no network needed) and a total check. The complete official Schematron rules need XSLT 2.0 (Java), which PHP cannot run. For a complete official check, run the KoSIT validator as a daemon on your own server (java -jar validator.jar -s scenarios.xml -D) and enter its URL, for example http://127.0.0.1:8080/, under Validation. Do not use third-party online validators for real invoices: they contain personal data.

10. Permissions (ACL)

Under System > Permissions > User Roles, CommerceGears > E-Invoicing:

• View E-Invoices and Download Files
• Generate, Send and Cancel E-Invoices
• Edit Buyer E-Invoice Details on Orders
• Settings

11. Troubleshooting

• No document is created: check that E-Invoicing is enabled for the store view, that the order was invoiced and that a rule matches the buyer (a German buyer counts as a business with a company, a VAT ID or the business purchase box ticked). Magento's cron must run.
• Status "Invalid": the document page lists the rule, for example BR-DE-2 (fill in the seller contact) or BR-DE-23 (enter your IBAN). Fix the settings or the buyer details and click Regenerate.
• A public body got ZUGFeRD: the reference was not a valid Leitweg-ID (wrong format or check digits). Correct it in the E-Invoicing box on the order page and create the XRechnung there.
• The ZUGFeRD PDF is refused (only with PDF Layout = Magento's invoice PDF): hybrid PDFs need a classic PDF. Magento's own invoice PDF works; PDFs from customised PDF modules that use compressed cross-reference streams are refused with a message. Switch to the German invoice layout.
• No download in My Account: downloads are for logged-in customers and documents that are ready, sent or delivered; check Download in Customer Account.

12. Uninstall

composer remove commercegears/module-e-invoicing-de
bin/magento setup:upgrade

Documents already created stay in E-Invoicing Core (files in var/commercegears_einvoicing/). Keep them for the legal retention period: the module never deletes documents or files.