> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/e-invoicing-integrations/zugferd.md).

# ZUGFeRD

## Synchronisation scope

| Synchronisation                                     | Direction         | When it runs                                                                 |
| --------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------- |
| Invoices and credit notes (XML embedded in the PDF) | Younium → ZUGFeRD | Whenever an invoice PDF is generated for a legal entity with ZUGFeRD enabled |

Not in scope: transmission to a network or recipient, received (supplier) invoices.

***

## Overview

The ZUGFeRD integration embeds structured invoice XML (CII format, ZUGFeRD 2.3) inside PDF documents using the extended profile by default. Younium builds an `InvoiceDescriptor` from invoice and legal entity data, validates basic or extended models, serialises XML, and attaches it to the PDF as `ZUGFeRD-invoice.xml` with MIME type `text/xml` and AF relationship `Alternative`.

## Authentication

There is no external connection and nothing to authenticate. The ZUGFeRD XML is embedded inside Younium when an invoice PDF is generated for a legal entity that has ZUGFeRD enabled.

## Profiles supported

| Profile                                                                 | Validator     | Notes                                                      |
| ----------------------------------------------------------------------- | ------------- | ---------------------------------------------------------- |
| **Basic**, **Comfort**                                                  | Supported     | Documents are built to the **Extended** profile by default |
| **Extended**                                                            | Supported     | The default profile                                        |
| **Minimum**, **BasicWL**, **XRechnung**, **XRechnung1**, **EReporting** | Not available | Selecting one of these does not produce a document         |

Saved XML uses `ZUGFeRDVersion.Version23`, format `CII`, embedded filename `ZUGFeRD-invoice.xml`.

## Eligibility and line filtering

Invoice lines are filtered with `FilterInvoiceLinesForDocument` using invoice type and `InvoiceSettings` before modelling (same pattern as other document outputs). Validation exceptions surface as `ZugferdValidationException`.

## General information mapping

| Younium Field                                              | ZUGFeRD descriptor                                                             |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `Invoice.InvoiceNumber`                                    | Invoice number                                                                 |
| `Invoice.InvoiceDate`                                      | Invoice date                                                                   |
| `Invoice.Currency.Code`                                    | Currency (must match supported enum mapping)                                   |
| `Invoice.Notes`                                            | Note on descriptor                                                             |
| Credit or negative total                                   | `InvoiceType.CreditNote` (document type 381)                                   |
| Any other invoice                                          | `InvoiceType.Invoice` (document type 380)                                      |
| Explicit correction flag with a resolved preceding invoice | `InvoiceType.Correction` (document type 384); see Credit notes and corrections |
| Fixed                                                      | Business process `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`                 |

## Party mapping — seller

| Younium Field                                                                                                    | ZUGFeRD party          |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `ApplicationLegalEntity` name, address, tax IDs                                                                  | Seller party block     |
| Invoice bank account (the account matching the invoice currency), otherwise `ApplicationLegalEntity.IBAN`, `BIC` | Seller payment account |

### Seller payment account

The legal entity's IBAN and BIC are used only when the invoice carries no bank account of its own. When the invoice has a bank account, that account is used as it stands and no field is borrowed from the legal entity, so a currency-specific account with a blank BIC or IBAN never inherits the legal entity's value. Wrong bank details are worse than none, because the buyer pays and nothing flags the error.

The IBAN and BIC are included only when the corresponding settings in the ZUGFeRD integration settings are on. The account number of the bank account is always included. A payment account is written whenever an IBAN or an account number is available; a BIC on its own is not written. An account with an account number but no IBAN is sent with the account number only, and no empty IBAN element is left in the XML.

The payment means type code is derived from this seller account, never from the buyer's account:

| Condition                                                                                  | Payment means code         |
| ------------------------------------------------------------------------------------------ | -------------------------- |
| Invoice currency is EUR and the seller IBAN starts with the country code of a SEPA country | 58 — SEPA credit transfer  |
| Seller account present in any other case (non-euro currency, IBAN outside SEPA, no IBAN)   | 30 — Credit transfer       |
| No seller account                                                                          | 1 — Instrument not defined |

Invoices without a seller account carry code 1 (the payment means group stays present, as EN 16931 requires).

> **Note on SEPA countries:** SEPA eligibility is decided by the first two characters of the seller IBAN, after trimming surrounding spaces, against the European Payments Council list of SEPA scheme countries. The check does not validate the IBAN itself. A value that is not an IBAN is treated as a plain credit transfer.

### Remittance information

The payment reference shown to the payer is the invoice's OCR number when the invoice has one, and the invoice number otherwise.

## Party mapping — buyer

The buyer address (street, postcode, city) is taken from the invoice's own address — the same address printed on the invoice PDF. If the invoice has no address of its own, Younium falls back to the account's default invoice address. The buyer country is read only from the invoice address and does not use this fallback.

| Younium Field                                                                     | ZUGFeRD party                                           |
| --------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `Invoice.InvoiceAddress`, falling back to `Invoice.Account.DefaultInvoiceAddress` | Buyer street, postcode, city                            |
| `Invoice.InvoiceAddress` country                                                  | Buyer country code                                      |
| `Invoice.Account.Name`                                                            | Buyer name                                              |
| Domestic vs cross-border                                                          | Affects tax category on lines (`isDomesticTransaction`) |

> **Note on buyer address vs. buyer country:** The buyer address falls back to the account's default invoice address when the invoice has none, but the buyer country never does — it always comes from the invoice address, since it also decides the domestic/foreign VAT category on the invoice.

Optional buyer IBAN from the buyer IBAN mapping on the account. When the mapping supplies an IBAN it replaces the buyer IBAN fallback in the ZUGFeRD settings, so the document carries a single debtor account. The buyer IBAN is written as the buyer's account for direct debit and does not affect the payment means code.

The invoice does not name a separate payee. Previously the buyer was written as the payee, which instructed the receiver to pay itself; the payee is now omitted, so payment goes to the seller.

## Line item mapping

| Younium Field                                   | ZUGFeRD line                                            |
| ----------------------------------------------- | ------------------------------------------------------- |
| Line net amounts, quantity, product/charge text | Trade line items                                        |
| `TaxItems`                                      | Tax category per line (see VAT exemption reasons below) |
| Extended profile                                | Additional extended line fields                         |

Tax breakdown groups by category and VAT rate; discrepancies between line tax sum and invoice tax are logged as warnings.

### VAT exemption reasons

The same reason text and code are used for a tax category wherever it appears — on the invoice-level VAT breakdown and on every line carrying that category — so the two always agree.

| Tax category               | Reason text            | VATEX code  |
| -------------------------- | ---------------------- | ----------- |
| E — Exempt from VAT        | Exempt from VAT        | —           |
| G — Export outside the EU  | Export outside the EU  | VATEX-EU-G  |
| AE — Reverse charge        | Reverse charge         | VATEX-EU-AE |
| K — Intra-Community supply | Intra-Community supply | VATEX-EU-IC |
| S — Standard rate          | None                   | None        |
| Z — Zero rate              | None                   | None        |

> **Note on standard and zero-rated invoices:** EN 16931 forbids a VAT exemption reason on a standard-rated or zero-rated invoice line or breakdown. Younium omits the reason entirely for categories S and Z, so a domestic invoice at the standard or zero rate validates correctly against the KoSIT validator and equivalents.

## Payment and totals mapping

| Younium Field       | ZUGFeRD totals     |
| ------------------- | ------------------ |
| Sum of line nets    | `lineTotalAmount`  |
| `Invoice` tax total | `taxTotalAmount`   |
| Grand total         | `grandTotalAmount` |
| Amount due          | `duePayableAmount` |

Rounded to two decimals with away-from-zero rounding.

## Credit notes and corrections

### Preceding invoice

A credit note or correction references the invoice it relates to (the preceding invoice number and date). Younium never references the document itself. It resolves the preceding invoice from the first of these sources that yields a value:

| Order | Source                                                                           | Notes                                                                                                                                                                                                                                   |
| ----- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1     | The link created when a credit is raised with **Credit invoice**                 | Credits only. It comes first because **Credit invoice** copies the original invoice's custom fields onto the credit, so a preceding invoice number mapped from them describes what the original corrected, not what the credit credits. |
| 2     | The `PrecedingInvoiceNumber` and `PrecedingInvoiceDate` mappings (invoice scope) | The only source for credits from change orders and for corrections. If only the number is mapped, the date is taken from the issued invoice with that number. If no date can be found, the date is left out rather than guessed.        |
| 3     | None                                                                             | The document carries no preceding invoice reference. The reference is optional in EN 16931.                                                                                                                                             |

### Document type

| Condition                                                    | Document type                                                                                                         |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| The correction flag is set and a preceding invoice resolves  | Correction (384), whether or not the invoice is a credit. A flagged credit is a correction of the invoice it credits. |
| The correction flag is set but no preceding invoice resolves | Invoice (380) or credit note (381), and a warning is logged                                                           |
| Credit or negative total                                     | Credit note (381)                                                                                                     |
| Anything else, including cancelled invoices                  | Invoice (380)                                                                                                         |

The correction flag is the `IsCorrectionInvoice` mapping (invoice scope) or, for tenants that still use it, the custom field configured in the ZUGFeRD settings (`IsCorrectionInvoiceCustomFieldMappingField`, truthy values `true`, `1`, `yes`, `y`, `on`). If both are set the document still carries one reference. A cancelled invoice is not treated as a correction, because only draft invoices can be cancelled and a cancelled invoice was therefore never issued.

> **Note on timing:** Mapped values are read when the PDF is rendered. A value added after an invoice is posted appears when the invoice is downloaded again, not in the PDF stored at posting. Set the mappings before posting.

## SEPA direct debit

When the account has a SEPA mandate on a EUR invoice, the payment means is SEPA direct debit (code 59) instead of the default credit transfer. The mandate comes from account-scope mappings.

| Mapping target         | ZUGFeRD field               | Use                                             |
| ---------------------- | --------------------------- | ----------------------------------------------- |
| `SepaMandateReference` | Mandate reference (BT-89)   | A mandate on a EUR invoice selects direct debit |
| `SepaCreditorId`       | Creditor identifier (BT-90) | Required with a mandate                         |
| `BuyerIBAN`            | Debited account (BT-91)     | The buyer's IBAN                                |

A mandate without a creditor identifier stops document generation with a validation message that names the missing value, because XRechnung requires it with code 59. A mandate on an invoice in any other currency is ignored. Accounts without a mandate keep the existing payment means.

## Custom fields

Correction flag uses a configured field configuration ID; renaming the underlying custom field without updating settings breaks correction detection.

Allowed custom mapping targets are constrained by `ZugferdAllowedFieldsProvider` (integration maintenance).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/e-invoicing-integrations/zugferd.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
