Choosing the document corridor for Germany (ZUGFeRD or PEPPOL)

Goal

Choose which document corridor to use for a German (DE) account: ZUGFeRD/Factur-X or PEPPOL. The choice is mandatory for DE accounts and determines which format POP generates.

Prerequisites

• A POP account with country set to DE.

Steps

1. The choice is made only from the POP account panel (the onboarding wizard or account-setup): there is no dedicated control in either the WordPress plugin or the Shopify app: both only show the current active status (a badge), read-only.
2. If you don’t choose explicitly, for a DE account with no registered PEPPOL legal entity, the default value is zugferd.
3. To switch to peppol, register a PEPPOL legal entity (see integrations/peppol): from that point the corridor is automatically forced to peppol and can no longer switch back to zugferd, the choice locks as soon as a PEPPOL legal entity exists (live or sandbox).

Verify

In the WordPress plugin, the ZUGFeRD section in settings shows the current status and credit consumption; in the Shopify app a “ZUGFeRD active” badge appears when the corridor is zugferd. In both cases the value shown reflects what’s set in the account panel, it isn’t editable from there.

Using ZUGFeRD once it’s active (WordPress)

When the account’s corridor is zugferd, the WordPress plugin replaces the separate XML/PDF buttons with a dedicated experience, both in the order list and in the order detail:

• ZUGFeRD button: downloads the hybrid PDF (the one with embedded XML), meant for everyday use.
• ZIP download: downloads all three files (hybrid PDF, standard PDF, EN16931 XML) in a single archive. It’s served from the local cache and doesn’t consume additional credits beyond the initial generation.
• Order-completed email: the hybrid PDF is automatically attached to the order-completed email. Resending that email from the order detail doesn’t delete the already-generated cached files, you can resend it as many times as needed without regenerating the bundle.

Good to know

• Every ZUGFeRD bundle generated consumes 1 credit (generation itself is the only billed action, unlike XML/UBL/KSeF where generation is free and only sending consumes a credit); re-downloading the same bundle from the cache (including the ZIP) doesn’t consume further credits.
• On Shopify, automatic generation on paid orders does not include ZUGFeRD documents: when the corridor is zugferd, automatic sending is explicitly skipped, because the bundle is made up of 3 files (visual PDF, EN16931 XML, hybrid PDF) and requires a manual action to choose what to generate.
• See api/zugferd for the API contract of the generated bundle.

Common errors

• “Germany requires a document corridor selection.”: a DE account hasn’t chosen a corridor yet, go to the wizard/account panel and select zugferd or peppol.
• “Invalid Germany document corridor. Allowed values: zugferd, peppol.”: a value other than the two allowed ones was sent, use exactly zugferd or peppol.
• Can’t switch back to ZUGFeRD after activating PEPPOL: expected behavior, once a PEPPOL legal entity is registered, the corridor stays locked to peppol.