Introduction

ZUGFeRD is a feature for creating hybrid electronic invoices. IOM keeps the human-readable PDF and embeds structured ZUGFeRD XML containing the invoice data. The established visual document is combined with machine-readable data so that recipients can process invoices and credit notes automatically without losing the familiar PDF representation.

The existing IOM document generation process is extended by the ZUGFeRD feature. For an enabled shop, IOM maps the data of an invoice or credit note to the ZUGFeRD data model, embeds the resulting XML in the generated PDF as PDF/A-3, and validates both the XML and the completed PDF before further processing. This concept focuses on the functional behavior and responsibilities; it does not replace the existing invoicing, transmission, or archiving processes.

This document introduces the ZUGFeRD feature in IOM and explains the main topics covered by this concept: supported documents, the user workflow, shop configuration, structured invoice data, validation, operations, and deployment acceptance.

It is mainly addressed to business users, shop administrators, and project stakeholders. It applies to IOM with the ZUGFeRD feature enabled and supports the functional understanding, configuration, testing, rollout, and operation of ZUGFeRD electronic invoices and credit notes.

The related business process is the IOM order-to-cash process, especially invoice creation, credit note creation, manual credit note creation, document delivery, and document archiving. The feature is activated per shop and becomes effective when the corresponding invoice or credit note PDF is generated.

The following knowledge is assumed:

• Basic knowledge of IOM shops, orders, invoices, credit notes, and document transmission

• Understanding of the difference between a human-readable PDF and structured XML data

• Basic knowledge of shop configuration and deployment environments

• Basic familiarity with invoice, tax, and payment information in Germany

Detailed knowledge of the ZUGFeRD standard or its technical XML schema is not required for business users. Technical implementation and integration stakeholders should additionally understand PDF/A-3, XML validation, EN 16931, and the recipient system's import and archiving capabilities.

Deployment-specific configuration, legal requirements, and integration details must be confirmed for the respective IOM environment.

References

• Guide - IOM eInvoice (ZUGFeRD)

Purpose and Benefits

ZUGFeRD enables electronic invoices as hybrid PDF invoices:

• The PDF remains readable for people.

• Structured ZUGFeRD XML is embedded in the PDF.

• Recipients can process the invoice data automatically.

• The business data continues to originate from the IOM invoice and credit note processes.

The feature extends the existing document generation. It does not replace the invoicing process or the transmission and archiving of documents.

Scope

Supported Documents

ZUGFeRD is attached only to a generated PDF. XML documents or other output formats are not enriched afterwards.

The applicable country and tax specification for this concept is Germany. Requirements beyond EN 16931 are therefore evaluated against the German specification.

Profile and Format

• ZUGFeRD version: 2.x

• Profile: EN 16931

• Result: PDF/A-3 with embedded ZUGFeRD XML

• Readability: The visual invoice remains unchanged.

User Workflow

1. An order is invoiced as before.

2. IOM generates the invoice or credit note as a PDF.

3. If ZUGFeRD is enabled for the relevant shop, IOM also generates structured invoice data.

4. The structured data is embedded in the PDF.

5. The resulting PDF is made available through the existing document and transmission process.

6. For a credit note, the structured output contains a reference to the original invoice if that reference is available in the invoicing process.

Manual credit notes follow the same process. Once the manual credit note has been created as a supported CREDIT_NOTE document, it can be enriched with ZUGFeRD when the feature is enabled for the relevant shop.

The download or transmission process does not fundamentally change for users. The difference is in the content of the PDF: it additionally contains machine-readable invoice data.

Shop-Level Activation

Activation is performed per shop through a ZUGFeRD shop configuration entry. A shop is active only if a configuration exists for it and enabled is set to true.

Seller master data should preferably be maintained in the shop configuration. For individual values, IOM can fall back to configured application properties or existing shop master data. The source used in a specific deployment must be agreed with the operator.

Minimum Data Requirements

The following information must be available at a minimum for a compliant output:

• Seller name

• Seller country

• At least one suitable seller identifier, such as a seller ID, legal registration identifier, or VAT identifier

• Invoice number and invoice date

• Buyer data

• Currency

• Invoice items with quantity, price, and tax information

If business-critical data is missing, ZUGFeRD validation may fail. See Validation and Error Handling.

Structured Invoice Content

IOM takes the data from the existing invoice document and maps it to the ZUGFeRD data model. The following information is typically transferred:

Header and reference data:

• Invoice or credit note number

• Issue date

• Due date, if available

• Currency

• Payment reference and payment terms, if available

• Order reference

• For consolidated invoices: included orders and billing period

Business parties:

• Seller data from the shop configuration and master data

• Buyer name and address

• VAT and other identification details, if available

• Payment data such as IBAN and payment means, if available

Items, shipping information, and taxes:

• Product number and description

• Quantity and standardized unit of measure

• Unit price and line amount

• Discounts, surcharges, and shipping costs, if present in the invoice model

• Tax category, tax rate, and tax amounts

• Shipping or delivery note information, if assigned to the invoice document

For credit notes, including manual credit notes, credited amounts are transferred according to the credit note model. A credit note also requires a reference to the original invoice where this is required by the business process and available in the source document. The person creating a manual credit note is responsible for ensuring that the relevant reference and business data are available.

Consolidated Invoices and Multiple Tax Rates

Consolidated invoices can combine multiple orders in a single invoice document. For traceability, order references and, if available, the billing period are included in the structured invoice data.

Invoice items with different tax rates are evaluated separately according to their tax characteristics. Surcharges and discounts must be assigned to the relevant business context so that net, tax, and gross amounts remain consistent.

Validation and Error Handling

IOM first validates the generated ZUGFeRD XML and then the completed PDF. The validation checks the data model, XML structure, embedding, and business rules of the selected profile.

Only a successfully validated result generates a valid eInvoice PDF.

If validation fails, no valid ZUGFeRD PDF is output. The technical error is logged and must be analyzed by the operator using the validation details.
Instead, a PDF is created that contains the invalid XML data and the corresponding error message as attachments. The PDF can be accessed in the Order Management Tool (OMT). You can find orders with such invoices or credit notes in the OMT under Orders | Order search by selecting the Business query value invalid invoice pdfs. These PDFs have the status invalid.
Typical causes include:

• Missing seller or buyer data

• Missing invoice number, date, or currency information

• Inconsistent line-item or tax amounts

• Missing mandatory reference for a credit note

• Inconsistent payment information

Validation and processing information is recorded in the application logs using the log.error, log.info, and log.debug levels.

The business correction must be made at the source of the invoice data or in the shop configuration. The document must then be generated again.

Known Issue: eInvoice Rounding Differences

In rare cases, some eInvoice readers can report a discrepancy of up to one cent when recalculating line totals. The cause is the different calculation logic of IOM. This logic ensures that multiple credit notes for a fully canceled order add up to exactly the original order price.
The eInvoice remains fully valid against the EN16931/Factur-X schema and schematron (for example, BR-CO-16) in every case. The discrepancy affects only an additional check that some importer libraries run. The standard does not mandate this check. Document generation and download continue to work.

Operations and Responsibilities

Before production activation, test at least one invoice and one credit note. Also test consolidated invoices, multiple tax rates, payment methods, and missing or optional data where they occur in the relevant shop.

The test scope must also include a manual credit note if manual credit notes are used in the shop.

Boundaries and Known Limitations

• ZUGFeRD is not generated for arbitrary document types.

• The current scope does not require project-specific fields or customizations.

• The current scope does not include document types other than invoices and credit notes.

• Activation is performed per shop, not globally for every document regardless of shop.

• A normal PDF is not automatically converted into a ZUGFeRD file if structured invoice data cannot be generated.

• Project- or customer-specific deviations may require a project-specific mapper or customization.

• Conformity of the generated document does not replace verification of the tax, legal, or organizational requirements of the relevant country and recipient.

• Transmission, archiving, and business approval of the document remain part of the existing IOM processes.

Deployment Acceptance Criteria

A deployment is considered functionally prepared when:

• ZUGFeRD is enabled for the intended shops.

• Seller name, country, and at least one seller identifier are maintained correctly.

• A test invoice is generated as PDF/A-3 with embedded ZUGFeRD XML.

• A test credit note is generated with the correct preceding-invoice reference.

• A manual credit note is generated as a valid ZUGFeRD document where manual credit notes are used.

• The documents are accepted by a suitable ZUGFeRD validator.

• The recipient system can read and process the XML data from the PDF.

• Error cases and the responsible operations contacts are documented.

Technical Reference Framework

This functional documentation is based on the following IOM concepts and components:

• ZUGFeRD shop configuration with activation switch and seller data

• ZUGFeRD-capable invoice mapper for invoices and credit notes

• Generation of structured XML from the IOM document model

• Embedding of the XML into the existing PDF as PDF/A-3

• XML and PDF validation before further processing

The concrete configuration and seller data are deployment-specific and must not be copied from the test environment examples.