normwerk

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, following VAT rules that are documented one scenario at a time against their legal source.

What it does ​

  • Maps a Medusa v2 order (and refunds → credit notes) to an 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 fixture is validated with the official validators (KoSIT Validator, Mustang, veraPDF), run in pinned Docker images by one command you can repeat yourself — 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). Buyers of a German seller elsewhere in the EU/EEA (except Italy and Poland, which run clearance platforms of their own), in Switzerland or the UK get an EN 16931 hybrid document (Factur-X/ZUGFeRD EN 16931). Where the rules can't decide a case safely — for example a B2B service to a business outside the EU — the invoice is refused with a named error instead of guessed. Norway, Denmark, and Sweden (Peppol BIS Billing 3.0) are next. Full matrix with target dates and legal mandates: supported countries.

Install ​

bash
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 was released on 2026-10-24 (Germany, B2B and B2G): @normwerk/einvoice-medusa and the core packages are on npm, each with npm provenance. Release notes and the conformance report run against the release: GitHub release.

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.