Native ZUGFeRD in Shopware: what the standard invoice does

On January 1, 2027, the e-invoicing transition period ends for many B2B shops: anyone whose total turnover exceeded €800,000 in the previous year may, as a rule, no longer send paper or PDF invoices to businesses in Germany (Sec. 27(38) no. 2 UStG). The obvious question is whether the shop needs an extension for this. For native ZUGFeRD in Shopware, the answer in many cases is no. Since version 6.6.10.0, the standard invoice has produced ZUGFeRD e-invoices, either as a separate XML file or embedded in the familiar PDF invoice (Shopware). This post shows what the feature does in detail, where it takes its data from and where a Shopware store still needs an addition.

What applies to invoice issuers from January 1, 2027

Since January 1, 2025, every business established in Germany has had to be able to receive e-invoices; an email inbox is already sufficient for that (BMF). For issuing invoices, however, a staggered transition period applies. In 2025 and 2026, all invoice issuers may still opt for a so-called other invoice instead, meaning paper or, with the recipient’s consent, a PDF sent by email, for example (BMF).

From 2027, a turnover threshold splits shops into two groups. Only businesses whose total turnover in the previous calendar year did not exceed €800,000 may keep using paper or another electronic format until December 31, 2027 (Sec. 27(38) no. 2 UStG). Invoices sent via electronic data interchange (EDI) have a separate deadline at the end of 2027 (Sec. 27(38) no. 3 UStG). Only once these transition periods have expired is the e-invoice actually mandatory in transactions between domestic businesses (BMF), with exceptions such as small-amount invoices and businesses under the small business scheme (BMF). Our 2027 deadline calendar for online shops puts the other dates of the year in context.

For a pure consumer shop, little changes, because the rules on mandatory e-invoicing only apply where there is a VAT obligation to issue an invoice at all, and invoices to consumers are not among them (BMF). Any shop that also sells to businesses in Germany is affected, for example through business customer accounts, purchase on account or quote requests in B2B e-commerce. In exactly these shops the invoice is often created in the shop itself, which is where the question about the standard feature becomes concrete.

What counts as an e-invoice and why ZUGFeRD qualifies

The German VAT Act defines the e-invoice by its form: it is issued, transmitted and received in a structured electronic format and allows electronic processing (Sec. 14(1) UStG). The format has to comply with the European standard on electronic invoicing, that is EN 16931, or be agreed between the parties and allow the complete extraction of the mandatory details (Sec. 14(1) UStG). A plain PDF does not meet this, because it has no structured format (BMF).

According to the tax authorities, XRechnung and ZUGFeRD from version 2.0.1 in particular meet the VAT requirements, with the exception of the MINIMUM and BASIC-WL profiles (BMF). ZUGFeRD is a hybrid format: a PDF that a person can read carries an XML file with the structured invoice data inside it. With mandatory e-invoicing, the order of precedence between the two parts has been reversed.

If the structured part of the invoice differs from the image part, the data in the structured part now prevails.

Federal Ministry of Finance, questions and answers on the introduction of mandatory e-invoicing, question 12a (own translation)

In practice this means: if the XML and the PDF view differ, the XML data applies (BMF). A payment term that only appears on the PDF, or an address that was only corrected in the printed view, does not count. That is exactly why it is worth looking at where Shopware gets the content of the XML from. How ZUGFeRD and XRechnung relate to each other and which profile fits which purpose is covered in our post on e-invoicing requirements for online shops.

Since when Shopware has generated ZUGFeRD natively

Since version 6.6.10.0, Shopware has generated e-invoices in ZUGFeRD format that comply with EN 16931 (Shopware). The invoice data is either embedded in the familiar PDF invoice or provided as a separate XML file (Shopware). Version 6.7.9.0 added further documents in ZUGFeRD format (Shopware): credit note and cancellation invoice, each again as XML or embedded. Together, that makes six variants to choose from in the dialog for creating a document.

The names in the table are the document types that Shopware creates in the database via migrations (Shopware source code). The 6.5 line, by contrast, does not include ZUGFeRD generation; the last release 6.5.8.19 contains no such code (Shopware source code). Anyone still running 6.5 therefore has a second reason to upgrade. Why security updates are running out there as well is explained in our post on Shopware 6.5 and the end of security updates.

What is in the XML: CII, EN 16931 and the XRechnung profile

For ZUGFeRD documents, Shopware uses the CII standard (Cross Industry Invoice), which is integrated into the ZUGFeRD format (Shopware). In the source code, the XML builder also sets the profile: it creates every document with the XRechnung 3 profile of the bundled ZUGFeRD library (Shopware source code). The reworked document generation, which already sits in the core behind a feature flag, explicitly writes XRechnung 3.0 into the document context as its identifier (Shopware source code).

This has two practical consequences. First, the XML follows the rules of XRechnung, which adds 21 national business rules to the EU standard (E-Rechnung Bund). Second, the CII syntax is sufficient: invoice issuers can choose one of the permitted syntaxes, and only recipients in public administration have to accept both (KoSIT). The fact that Shopware does not produce XML in the second syntax, UBL, is therefore not a legal shortcoming.

<rsm:CrossIndustryInvoice>
  <rsm:ExchangedDocumentContext>
    <ram:GuidelineSpecifiedDocumentContextParameter>
      <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</ram:ID>
    </ram:GuidelineSpecifiedDocumentContextParameter>
  </rsm:ExchangedDocumentContext>
  <rsm:ExchangedDocument>
    <ram:ID>[invoice number from the number range]</ram:ID>
    <ram:TypeCode>[document type: invoice, credit note or correction]</ram:TypeCode>
  </rsm:ExchangedDocument>
  <rsm:SupplyChainTradeTransaction>
    <ram:ApplicableHeaderTradeAgreement>
      <ram:BuyerReference>[shop order number]</ram:BuyerReference>
      <ram:SellerTradeParty>[business settings]</ram:SellerTradeParty>
      <ram:BuyerTradeParty>[customer and billing address]</ram:BuyerTradeParty>
    </ram:ApplicableHeaderTradeAgreement>
    <ram:ApplicableHeaderTradeSettlement>
      <ram:SpecifiedTradeSettlementPaymentMeans>[only for invoice, prepayment, cash]</ram:SpecifiedTradeSettlementPaymentMeans>
      <ram:SpecifiedTradePaymentTerms>[payment due date]</ram:SpecifiedTradePaymentTerms>
    </ram:ApplicableHeaderTradeSettlement>
  </rsm:SupplyChainTradeTransaction>
</rsm:CrossIndustryInvoice>

Before output, Shopware checks the assembled document with a validator. If it finds violations, generation stops with an error message instead of storing a faulty file (Shopware source code). For development of the core there is an additional check that compares generated sample documents against the EN 16931 business rules using the KoSIT validator (Shopware source code). The tax authorities recommend validating when an e-invoice is created and sent, even though validation is not a requirement for recognition for tax purposes (BMF). For your own shop, this means: running one test invoice per payment method through a validator belongs before going live.

The data basis: business settings and order data

The shop does not maintain the content of ZUGFeRD documents in a separate area. The basis is the settings of the respective standard document under Settings > Commerce > Documents; Shopware uses the business settings stored there to generate the ZUGFeRD documents (Shopware). The source code shows which details go into the XML (Shopware source code):

• Seller: company name, street, postal code, city and country from the business settings
• Tax details: company tax number and company VAT ID, both as the seller’s tax registration
• Contact: company email address, company phone and the entry under business executive as contact person
• Bank details: IBAN and BIC, but only for the payment methods invoice and prepayment
• Buyer: first and last name, company name, customer number, email address and billing address from the order
• Buyer reference: the shop’s order number

Two points deserve particular attention. The first is the due date. Shopware sets the payment term in the XML from the field “Payment due date”; if it is empty, the code uses 30 days from creation (Shopware source code). The value appears only in the XML, not on the invoice itself, and it needs a plus sign in front (Shopware), so “+14 days” rather than “14 days”. Because the XML prevails in hybrid invoices (BMF), the field should match the payment terms printed in the PDF text. Otherwise the invoice carries two different payment terms, and the legally decisive one is the invisible one.

The second point is the bank details. Shopware writes IBAN and BIC into the XML only for purchase on account and prepayment, and a cash note for cash payment; for all other payment methods, the payment information remains empty (Shopware source code). For orders that are already paid, the XML records the amount paid (Shopware source code). How to safeguard purchase on account in business-to-business sales is covered in our post on credit limits for purchase on account; what each payment method costs the shop is calculated in the post calculating payment methods.

• Company name and full address are maintained, including the country
• Tax number and VAT ID are entered in the business settings
• The company email address leads to an inbox that handles queries about invoices
• IBAN and BIC are stored as soon as the shop offers purchase on account or prepayment
• The payment due date matches the payment term in the PDF and starts with the plus sign
• Business customers enter their company name when registering so that it appears in the buyer details; how to check this is shown in our post on business verification at registration

Automatic generation: the document creation flow

Manually, a ZUGFeRD document is created in the order: in the dialog for creating a document, the toggle “Show ZUGFeRD variants” displays the available variants, after which you select the one you need (Shopware). Variants labeled “embedded” contain the XML inside the PDF, the others deliver it as a separate file (Shopware). For day-to-day operation, a manual step per order is not a solution, though.

Shopware therefore lets you add the ZUGFeRD documents to the document creation flow so that they are generated automatically once an order reaches a certain status (Shopware). Credit notes and cancellation invoices require a previously created invoice because they refer to it (Shopware). The XML of the cancellation invoice contains the reference to the number and date of the original invoice, and Shopware sets the document type there to corrected invoice (Shopware source code). How cancellations, credit notes and corrections differ is explained in our post on ZUGFeRD cancellation invoices and credit notes.

1. Choose the trigger: create or open a flow for the right moment, for example a change in order or payment status
2. Set the variant: add the ZUGFeRD variant to the document creation action, for business customers usually the embedded invoice
3. Limit the scope: use a condition so the flow only applies to business customers, for example via the customer group
4. Connect sending: add the generated document as an attachment to the flow’s email action
5. Test: run one test order per payment method and check whether XML and PDF carry the same amounts, due dates and addresses

How triggers, conditions and actions work together in general is explained in our post on the Shopware Flow Builder. For e-invoicing, one additional flow or an extension of the existing invoice flow is usually enough.

Where the standard stops

For invoices that the shop itself issues to businesses in Germany, the standard usually covers what VAT law requires. Four situations go beyond that. The overview shows where the standard is enough and where an addition comes in.

Invoices to federal authorities with a routing ID

Anyone supplying the federal administration has to state, in addition to the mandatory VAT details, a routing identification number (Leitweg-ID), the bank details, the payment terms and an email address, among other things (Sec. 5 ERechV). In the XRechnung standard, the routing ID belongs in the buyer reference field (BT-10) and is mandatory there (E-Rechnung Bund). Shopware writes the shop’s order number into exactly this field (Shopware source code). For invoices to businesses this is permitted, because recipients there may give their suppliers an identifier of their choice for the field (KoSIT). An invoice to a federal authority, however, cannot be delivered without a routing ID; the platform rejects formally faulty invoices automatically (Sec. 4 ERechV).

Two details add to this. In Shopware, the bank details only end up in the XML for purchase on account and prepayment (Shopware source code). And the federal government only accepts the ZUGFeRD profile XRECHNUNG as a purely structured XML file without a visual format (E-Rechnung Bund), meaning the “ZUGFeRD Invoice” variant without a PDF. Submission takes place via the invoice receipt platform, among other channels by upload, email or Peppol (E-Rechnung Bund); prior registration with a user account is required (Sec. 4 ERechV). The federal government and the states each assign routing IDs themselves (KoSIT), and states and municipalities apply their own rules.

Sending via Peppol

Shopware does not support Peppol natively, and according to the vendor there is no commitment to native support (Shopware). The reasoning in the documentation is factual: Peppol is a network, not a format, and Germany mandates formats such as XRechnung and ZUGFeRD, but not a network (Shopware). This matches the tax authorities’ position that the law does not prescribe a particular transmission channel; sending by email is also possible (BMF). Peppol becomes relevant when customers abroad want to receive invoices through it or when the ERP is connected to an access point anyway. Our post on Peppol for B2B shops describes how the network is structured.

Invoices from the ERP

In B2B, the invoice is often not created in the shop. According to the vendor documentation, it is usually issued by the ERP or financial system (Shopware). In that case, the shop’s ZUGFeRD feature is not the right place, because two systems with their own invoice numbering would get in each other’s way. The e-invoice then belongs in the system of record, and the shop hands over the order data. That is an integration topic, for example with SAP Business One or the handover to DATEV.

Tax-exempt deliveries to other EU countries

For line items with a tax rate of 0%, the code sets the tax category for zero-rated goods (Shopware source code). The underlying code list has a separate category for tax-exempt intra-community supplies, as well as one for reverse charge (ZUGFeRD library). The standard does not write the buyer’s VAT ID into the XML (Shopware source code). The e-invoicing obligation only covers supplies between businesses established in Germany (Sec. 14(2) UStG). Anyone who still sends ZUGFeRD to customers in other EU countries should check these cases specifically.

Custom development: where Shopware provides for adjustments

Nobody has to rewrite the core to close these gaps. During generation, Shopware dispatches events that an extension can hook into: one per invoice line and one after the document has been assembled and before it is validated and output (Shopware source code). At this point, for example, the buyer reference can be replaced with a routing ID that the customer entered when ordering.

<?php declare(strict_types=1);

namespace Example\RoutingId;

use Shopware\Core\Checkout\Document\Zugferd\ZugferdInvoiceGeneratedEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

// Sketch: write the routing ID (Leitweg-ID) from an order custom field into the buyer reference (BT-10)
final class BuyerReferenceListener
{
    #[AsEventListener]
    public function __invoke(ZugferdInvoiceGeneratedEvent $event): void
    {
        $routingId = $event->order->getCustomFields()['example_routing_id'] ?? null;

        if (\is_string($routingId) && $routingId !== '') {
            $event->document->getBuilder()->setDocumentBuyerReference($routingId);
        }
    }
}

The sketch reads the routing ID from a custom field of the order and only sets it if one is present; orders without a routing ID keep the order number. Further details can be added the same way, such as the buyer’s VAT ID. How the custom field gets into the checkout and who fills it in belongs in the same plan, because the contracting authority communicates the routing ID when placing the order (E-Rechnung Bund).

Retention and everyday checks

Invoices must be kept for eight years (Sec. 14b UStG). For an e-invoice, at least the structured part must be kept intact in its original form (BMF). In the embedded variant, the XML sits inside the PDF; in the separate-file variant, the XML itself belongs in the archive. Shopware creates the documents in the documents section of the respective order (Shopware); whether that is sufficient as an archive depends on your own retention procedure. In many shops, accounting takes care of this when documents flow on through the DATEV integration.

For spot checks in everyday work, a readable view of the XML helps. Via the ELSTER portal, the tax authorities provide a viewer that displays invoices in XRechnung or ZUGFeRD format in readable form (BMF). A short check routine after every shop update makes sense: one test order per payment method, open the generated document, compare amounts, tax rates, due date and addresses with the PDF.

The switch before the turn of the year

Until the turn of the year, the switch can be planned in this order:

1. Check the version: is the shop running 6.6.10.0 or later? Credit notes and cancellations as ZUGFeRD are available from 6.7.9.0 (Shopware).
2. Clarify the threshold: if total turnover in 2026 exceeded €800,000, e-invoices must be used for issuing from January 1, 2027 (Sec. 27(38) UStG). Your tax advisor handles the assessment of the individual case.
3. Maintain the data basis: complete the business settings and align the due date with the payment term in the PDF.
4. Automate the process: add the ZUGFeRD variants to the document creation flow and limit it to business customers.
5. Test and inform: validate test invoices, inform business customers about the new format and plan special cases such as authorities or Peppol separately.

How we support the switch

We review the version, business settings and flows of your shop, generate test documents for each payment method and validate the XML against the EN 16931 rules. Where the standard is not enough, we develop the addition individually, for example the routing ID for public-sector customers or the handover to the ERP. More about our approach is on the page ZUGFeRD and XRechnung; updates and checks after every version jump are handled by our Shopware maintenance.