EN 16931 e-invoicing for Medusa v2

From 2027-01-01, a PDF alone stops being a valid invoice for German B2B transactions above €800k turnover, and from 2028-01-01 for everyone — the buyer's software needs a structured, machine-readable document. normwerk/einvoice builds that document straight from a Medusa v2 order: a KoSIT-validated XRechnung 3.0 XML, optionally embedded into a PDF/A-3b as ZUGFeRD/Factur-X, with the VAT rule it applied recorded and cited against its legal source.

What it does

• Maps a Medusa v2 order (and refunds → credit notes) to a full EN 16931 Invoice.
• Serializes it as UN/CEFACT CII, targeting the XRechnung 3.0 CIUS.
• Embeds the XML into a PDF/A-3b (ZUGFeRD/Factur-X hybrid) — your own PDF, or a bundled renderer.
• Every generated field is checked against the vendored EN 16931/XRechnung schema text, and every fixture is validated with the official validators (KoSIT Validator, Mustang, veraPDF) in CI — not a reimplementation of what those tools check.
• Ships two independent differential oracles so a shared bug in one implementation doesn't read as agreement. Details: how we verify.

Where it applies today

Germany — seller VAT rules and both B2B and B2G buyer profiles (XRechnung 3.0, ZUGFeRD 2.x/Factur-X, PDF/A-3b). Any EU/EEA, Swiss, or UK buyer of a German seller gets a correct EN 16931 hybrid document too. Norway, Denmark, and Sweden (Peppol BIS Billing 3.0) are next. Full matrix with target dates and legal mandates: supported countries.

Install

npm install @normwerk/einvoice-medusa @normwerk/einvoice-model @normwerk/einvoice-commerce @normwerk/einvoice-cii

Then follow the quickstart — a real Medusa v2 project fulfilling its first order into a KoSIT-passing XRechnung, in about 30 minutes.

Status

v0.1.0 targets 2026-12-01 (Germany, B2B and B2G). The code exists and passes the official validators in CI; the repository is not public yet and the @normwerk/* packages are not on npm yet. This page ships ahead of that release on purpose — GitHub is where to watch for it.

Not tax advice

This project verifies that the documents it produces pass the official validators. The VAT rules it applies are documented one scenario at a time with their legal source, and what an EN 16931 validator run does not catch is written down explicitly: tax semantics. Verify these rules with your own tax advisor before relying on them — you remain responsible for your invoices.

Commercial support

Implementation, adaptation to your stack, and support retainers. Learn more →

MIT licensed. Source on GitHub. Changelog.