Since Shopware 6.7.15.0, released on October 1, 2026, the core contains a rewritten document generation, for now behind the feature flag DOCUMENT_GENERATION_REWORK (Shopware release notes). This changes a lot for invoices: one document type produces several formats in a single run, ZUGFeRD is no longer a document type of its own, and the company information moves from the document template to the basic information settings per sales channel. With 6.8 the new generation becomes the default, with 6.9 the legacy path goes away (Shopware release notes). This article explains what document generation v2 means for your invoices, why the test belongs in a staging environment and how to prepare company data, templates and plugins.
What Shopware 6.7.15.0 changes in document generation
With 6.7.15.0, Shopware ships a new, opt-in implementation of order document generation (Shopware release notes). It replaces the legacy generation, which Shopware plans to deprecate with 6.8 and remove with 6.9 (Shopware release notes). It is switched on with the feature flag DOCUMENT_GENERATION_REWORK. Without the flag, the store runs purely on the legacy path (Shopware release notes). If you do nothing, you will not notice the rebuild in 6.7.
The label Shopware itself uses matters here: the release notes list v2 as experimental. Classes intended to become public API carry the @experimental annotation and, according to Shopware, may change in any release (Shopware release notes). Only with 6.8 does v2 become the default and the annotated surface the stable public API (Shopware release notes). The new path is therefore there to be tried out, not for the invoicing process in the year-end season.
Timeline: 6.7 opt-in, 6.8 default (opt-out), 6.9 legacy implementation and flag removed.
Shopware, Release notes 6.7.15.0
The three phases at a glance
| Version | New generation (v2) | Legacy path (v1) | What store operators do |
|---|---|---|---|
| 6.7, current line | optional, flag off by default | default | switch on and test in staging |
| 6.8 | default, can be switched off | still present, marked as deprecated | check extensions for v2 beforehand or deliberately switch v2 off |
| 6.9 | the only path | removed, as is the flag | have all extensions moved to v2 |
The architecture decision record on the migration describes the same three phases and adds a fourth: after 6.9, cleanups of the database schema follow (Shopware ADR). For merchants and partners, Shopware gives a short recommendation per version there. For 6.7 it reads: opt in to v2 and test it, explicitly in staging (Shopware ADR). Before upgrading to 6.8, every extension that touches documents should be verified as v2 ready. If one is not, v2 can be switched off, the upgrade carried out safely and the migration done later (Shopware ADR). In 6.9 this choice no longer exists (Shopware ADR).
Shopware states that merchants can switch back at any time (Shopware release notes). That is a safety net for testing, but no reason to run real invoices through a path whose interfaces may still change.
One document type, four formats from a single run
The biggest change concerns the relationship between document type and file format. A document type, meaning invoice, cancellation invoice, delivery note or credit note, can produce several formats in a single generation call: HTML, PDF, ZUGFeRD XML and PDF with embedded ZUGFeRD XML (Shopware release notes). All formats of one document are rendered from the same data, share the same document number and are stored as separate files (Shopware release notes). Merchants configure per document type which formats are generated (Shopware release notes).
Until now this worked differently. The legacy system coupled document type and file format, so every combination of type and format needed its own renderer (Shopware documentation). That leads to the second change: ZUGFeRD is no longer a document type of its own but a file format of the invoice, cancellation invoice and credit note types (Shopware release notes). If you currently generate a separate ZUGFeRD document next to the PDF invoice, v2 gives you a single invoice with two or more files.
HTML
The version for the browser. If a store switches back to the legacy path, it takes the slot of the accessible version of a document there (Shopware ADR).
The familiar invoice for printing and sending. The legacy surfaces default to the PDF (Shopware ADR).
ZUGFeRD XML
The structured part of the e-invoice as a separate file, for example for handing over to accounting or the ERP.
PDF with embedded XML
The hybrid form that used to be a ZUGFeRD type of its own. If the structured part and the image part differ, the data in the structured part is authoritative (BMF).
Generating all formats from one data basis fits this order of precedence: the PDF and the XML of an invoice should not drift apart. A second rule comes on top. Each generation run snapshots the order into a dedicated order version, so a document shows the state at the time of generation (Shopware release notes). File names receive configurable name parts per format. If two formats with the same file extension would end up with the same name, Shopware rejects the setting when it is saved (Shopware release notes).
One detail matters for sending documents to customers and is easy to miss in a test: mail attachments and the archive download include all generated formats by default, and the mail actions in Flow Builder can select specific formats (Shopware release notes). If you switch on four formats for invoices, you will send four attachments unless you adjust the flows. That is why the mail flows belong in every test run.
Company information per sales channel and the five required fields
The company details printed on documents, meaning name, address, tax and bank details and the logo, move to a new card under Settings > Basic information called “Company information” (Shopware release notes). They are maintained there per sales channel, no longer per document type (Shopware release notes). The card only appears once the flag is switched on (Shopware source code). Until now these details lived in the document templates. Shopware ships global templates for delivery note, invoice, credit note and cancellation invoice for this, which can be overridden per sales channel with custom templates (Shopware documentation).
Shopware does not migrate existing values into the new card (Shopware release notes). That sounds like data loss, but it is not: as long as the card is empty for a sales channel, v2 reads the legacy document settings (Shopware release notes). A store that flips the flag and changes nothing else therefore prints the same company details as before at first. Whether generation succeeds does not depend on the missing migration, but on whether the details are complete in the place where v2 reads them.
What is new is the check: if the name, street, zip code, city or country is missing, generation fails with a clear error instead of silently producing an incomplete document (Shopware release notes). The source code implements exactly that. Name, street, zip code, city and country are required fields of the company information, all other fields are optional (Shopware source code).
When generation fails
In practice, the decisive question is when the legacy settings apply and when they do not. In the 6.7.15.0 source code, v2 uses the new card as soon as a single field there holds a value. Only when all fields are empty does v2 read the legacy document template (Shopware source code). Values entered for all sales channels count for every individual channel (Shopware source code). This results in three typical paths to failure:
- Card partly filled: someone enters only the logo or the email address in the new card. From that moment, v2 no longer reads any details from the document template, name and address are missing, and generation fails.
- Template incomplete: the card is empty, but a required field is missing in the legacy template of the document type concerned, for example the city in the delivery note template. Then v2 fails for that document type while the invoice goes through.
- Country not selected: the country is a selection field. Without a valid selection, generation fails as well (Shopware source code).
The easiest way to avoid all three traps is to fill in the new card completely for every sales channel as soon as the flag is switched on in the staging environment and before the first test document is generated. Before that, the Administration does not show the card (Shopware source code). After that, the result no longer depends on what is in which document template.
What v2 checks and what German VAT law requires
The new check covers the sender address, not all mandatory details of an invoice. Among other things, an invoice must contain the full name and the full address of the supplier (Sec. 14(4) UStG). The law also requires the tax number or the VAT identification number (Sec. 14(4) UStG). In v2, these two fields are optional (Shopware source code). An invoice without a tax number therefore passes generation but does not meet the mandatory details.
| Detail | Checked by v2 before generation | Mandatory under Sec. 14(4) UStG |
|---|---|---|
| Name of the supplying company | yes, fails if empty | yes, full name |
| Street, zip code, city, country | yes, fails if a field is missing | yes, full address |
| Tax number or VAT ID | no, optional | yes, one of the two |
| Bank details, logo, email, phone | no, optional | not among the details under subsection 4 |
So the v2 check does not replace a review of the invoice content, it only prevents documents without a sender address. The tax number and the VAT identification number belong on the list when setting up the card.
Custom plugins, apps and templates
For stores with customized invoices there is good news: Twig template overrides keep working, because v2 renders the same templates under @Framework/documents/*.html.twig (Shopware release notes). According to Shopware, extensions that only change how a document looks are largely unaffected (Shopware ADR).
Code that hooks into the generation is a different matter. The legacy extension points, meaning the document.renderer and document_type.renderer tags, the legacy document events and decorators of the legacy DocumentGenerator, are not invoked by v2 (Shopware release notes). During the transition, both variants can be registered side by side (Shopware release notes). What v2 offers instead:
- Plugins register document types, data providers and renderers as tagged services:
shopware.document_v2.type,shopware.document_v2.providerandshopware.document_v2.renderer(Shopware release notes). - Apps register custom document types through a new
<documents>block in the manifest. Adocument-generationscript hook enriches the data (Shopware release notes). - Limit for apps: custom formats, renderers or typed data providers stay plugin-only (Shopware documentation).
- New events:
document.generation.completedanddocument.generation.deletedreport generated and deleted documents including document number and order reference and can be selected as triggers in Flow Builder (Shopware release notes).
The new events are especially interesting for integrations, because document.generation.completed fires for both paths, the legacy one and v2 (Shopware release notes). A custom handover to accounting or an ERP can therefore already be based on an event in 6.7 that works in both flag states, for example for the DATEV integration or an ERP. Which questions come first when choosing one is covered in our article on ERP selection for online retailers.
In the 6.7.15.0 source code, the event for a generated ZUGFeRD invoice carries a note that it will be replaced with 6.9.0; the XML is then produced by the v2 XML renderer without a public builder API (Shopware source code). What today’s standard invoice writes into the XML is described in our article ZUGFeRD straight from Shopware.
Existing documents and the way back
Switching to v2 does not regenerate past documents. The legacy ZUGFeRD types, meaning the two invoice types and the four cancellation and credit note variants, are shown unchanged in the v2 interface under their old name and for download (Shopware ADR). A backfill adds the metadata v2 needs to old documents. It is prepared in 6.7 but only relied upon in 6.9 (Shopware ADR). According to Shopware, it does not touch the actual files (Shopware ADR).
This matters for retention. Invoices have to be kept for eight years (Sec. 14b UStG), and for an e-invoice at least the structured part must be kept intact in its original form (BMF). According to Shopware, documents that have already been generated remain fully accessible after 6.9 without regeneration (Shopware ADR).
A way back is provided as well: during the 6.7 and 6.8 lines, merchants can switch freely between both paths (Shopware ADR). Shopware names one limitation itself. The legacy surfaces show at most two formats per document and default to the PDF (Shopware ADR). A document generated in v2 without a PDF can only be reached after switching back through an explicit file-type request (Shopware ADR). If you generate only XML for testing, you should know this before switching back.
Nothing changes for customers when downloading. They download v2 documents through the existing routes in the storefront and the Store API, and the URLs stay the same (Shopware release notes).
Test run in the staging environment: step by step
The test belongs on a copy of the store, a staging environment, regardless of whether the store runs on our Shopware hosting or with another provider. Shopware itself recommends exactly this approach for 6.7 (Shopware ADR). A complete test run typically follows this order:
- Update staging: bring the test environment to the production state, at least 6.7.15.0, with the same plugins and apps.
- Record extensions: list plugins and apps that touch documents, custom Twig overrides and all flows with document or mail actions.
- Flip the flag: switch on
DOCUMENT_GENERATION_REWORKin the staging environment only. Thefeature:enablecommand clears the cache as it does so (Shopware source code). - Fill in company information: in the card, which only becomes visible now, enter all five required fields for every sales channel plus the tax number or VAT identification number, bank details and logo.
- Choose formats: decide per document type which formats are generated. For invoices to business customers, that is usually the PDF with embedded XML.
- Run test orders: generate an invoice, delivery note, cancellation invoice and credit note per sales channel, with the store’s tax rates and discounts.
- Check results: review company details, number ranges, file names, mail attachments and the XML with the validation tool your accounting uses.
- Switch back and record: switch the flag off again, document the findings and plan the porting of extensions.
[OK] The following features were enabled: DOCUMENT_GENERATION_REWORK
A staging copy contains real customer data and often the credentials for accounting, the ERP and payment providers. Before the first test document, outgoing mail is intercepted and all integrations are switched to test accounts or turned off.
Timeline: e-invoicing mandate, Black Week and Shopware 6.8
The changeover falls into a period in which invoices are in focus anyway. Since January 1, 2025, businesses have had to be able to receive e-invoices (BMF). They have to issue e-invoices for supplies to other businesses in Germany (Sec. 14(2) UStG), but with transition periods. For supplies up to the end of 2026, all businesses may still send paper invoices or, with the recipient’s consent, other electronic formats such as a PDF (Sec. 27(38) UStG). For supplies in 2027, this only applies if total turnover in the previous year did not exceed €800,000; EDI procedures have a transition rule of their own (Sec. 27(38) UStG).
For many B2B stores this means e-invoicing with ZUGFeRD and XRechnung has to work at the turn of the year, and through the path that is proven today. Since 6.6.10.0, Shopware has created e-invoices in the ZUGFeRD format (Shopware documentation). That path remains in 6.7. Document generation v2 belongs in the staging environment in parallel, not in production between Black Week and the first invoice run of the new year.
For 6.8, Shopware has so far named only the year: the next major version is planned for 2027 (Shopware). The announcement gives no exact date. What is due before then anyway is covered in our article on the Shopware 6.8 upgrade. With 6.8, v2 is the default, and an extension that only knows the legacy path then works only for merchants who explicitly switch v2 off (Shopware ADR).
- Until Black Week: record extensions, fill in company information in staging, complete the first test run. Change nothing in production.
- December: secure the invoicing process for the turn of the year on the legacy path and commission the porting work.
- First half of 2027: move plugins and apps to the v2 extension points and recheck every new release of the 6.7 line with v2 switched on.
- Before upgrading to 6.8: decide whether v2 becomes the default with the upgrade or stays switched off for the time being.
- By 6.9: all extensions on v2, because switching back is no longer possible after that (Shopware ADR).
Shopware explicitly describes switching off in 6.8 as an option: if an extension that touches documents is not ready, v2 is switched off, the upgrade is carried out and the migration is done later (Shopware ADR).
Cancellations, credit notes and advance payments in B2B stores
In B2B stores, the invoice often comes with further documents. In v2, the cancellation invoice and the credit note are document types of their own, and ZUGFeRD is a format of both (Shopware release notes). Which codes and references a correction needs in the XML is covered in our article on ZUGFeRD cancellation invoices and credit notes. How advance payment and final invoice work together across the turn of the year is shown in the article on the advance payment invoice in B2B stores.
Custom developments for such cases are exactly the extensions that have to be revisited during the switch. If you are planning custom document types for B2B e-commerce now, it makes sense to build them against the v2 extension points right away. The same release also brings changes to the MCP server (Shopware release notes). Which permissions AI agents get there is covered in our article on AI agents in the Shopware Administration.
How we support the changeover
As a Shopware agency, we test v2 in a staging copy of your store: company information per sales channel, formats per document type, mail flows and the XML from test orders. We port extensions that touch documents to the new extension points, registered in parallel for the transition.
Test run on staging
Recording of extensions, filled-in company information and test orders per sales channel, with a list of findings instead of a switch in production.
Porting extensions
Custom document types, data providers and renderers for v2, built by our custom programming team and secured with tests.
Support up to 6.9
On request, we also check new releases with v2 switched on as part of our Shopware maintenance.
The effort depends on how many extensions that touch documents the store contains. A reliable estimate is possible after the inventory. Tell us about your setup through the contact form.
This article is based on the release notes for Shopware 6.7.15.0, the architecture decision record “Migration strategy from document generation v1 to v2” including its amendments, the developer documentation on Document (v2) and its extension points, the Shopware documentation on document settings and orders, the Shopware source code of version 6.7.15.0 on GitHub, Shopware’s announcement on the 6.8 roadmap, Sections 14, 14b and 27 of the German VAT Act (UStG) and the BMF questions and answers on e-invoicing. All information retrieved on November 2, 2026. This article does not replace a tax assessment of the individual case.
No. In 6.7, v2 is optional, and without the flag the store runs purely on the legacy path (Shopware release notes). Shopware recommends testing v2 in staging in 6.7 (Shopware ADR). In production, it is usually best to leave everything as it is before Black Week and the turn of the year.
No. Shopware does not migrate the values into the new card, but as long as the card is empty for a sales channel, v2 reads the legacy document settings (Shopware release notes). As soon as you fill in a field in the card, v2 uses only the card (Shopware source code).
Usually a required company detail is missing: name, street, zip code, city or country (Shopware release notes). Common causes are a partly filled company information card or an incomplete template of the document type concerned.
Twig template overrides keep working because v2 renders the same templates (Shopware release notes). Plugins that feed custom formats, types or data through the legacy extension points, however, are not invoked by v2 (Shopware release notes). They need to be ported to the new extension points.
They are kept and remain available. The legacy ZUGFeRD types appear in the v2 interface under their old name for download (Shopware ADR). According to Shopware, generated documents remain accessible after 6.9 without regeneration (Shopware ADR).
Temporarily, yes: in 6.8, v2 is the default but can be switched off (Shopware release notes). With 6.9, the legacy path and the flag are removed (Shopware release notes). We support the porting of custom extensions as part of our Shopware maintenance.