Einvoice medusa

@normwerk/einvoice-medusa

A thin Medusa v2 plugin for German e-invoicing (XRechnung 3.0 / ZUGFeRD, EN 16931): subscribes to order.fulfillment_created, order.fulfillment_canceled, payment.refunded and order.canceled — an invoice per fulfillment, a credit note per refund or cancellation — maps the order to @normwerk/einvoice-commerce's invoice model, and stores the result — idempotently, with no duplicate documents on event redelivery. No tax logic and no XML live in this package; that's @normwerk/einvoice-commerce/@normwerk/einvoice-cii's job, kept platform-agnostic.

The seller is in Germany. What each buyer receives — the full list, with the territories refused, is in docs/supported-countries.md:

Not supported: 🇮🇹 Italy (SDI), 🇵🇱 Poland (KSeF) — clearance platforms with an XML of their own, which no EN 16931 document can serve; out of scope. A buyer anywhere else, and a seller outside Germany, are refused too.

A PDF/A-3 hybrid from any PDF renderer you supply (including a bundled one, @normwerk/einvoice-pdfa's renderInvoicePdf), or XML only. The plugin numbers and issues the invoices itself: next to another plugin that issues invoices, the buyer gets two invoices for one supply — turn invoicing off in the other plugin. Documents are stored in Medusa's own File Module (private), with an admin "E-Invoices" widget on the order page and a Store API endpoint for a customer to fetch their own e-invoice. Each issued or refused document is announced on Medusa's event bus (einvoice.document_issued, einvoice.issuance_blocked; payload types from @normwerk/einvoice-medusa/events), and an order's documents are readable with the order (einvoice_documents) — so a shop's own code can mail the invoice to the buyer or hand it to accounting.

Compatibility

Supported: Medusa 2.12–2.15 and 2.18 or later 2.x — the releases the end-to-end suite passes on (a real store, from checkout to a validated invoice, credit note and refund), each minor line run at its latest patch. The peer dependencies declare exactly that range, and on any other release the plugin refuses to start (UnsupportedMedusaVersionError) rather than run where it has not been shown to issue correct invoices. Need another release? A pull request is welcome, or write to hello@normwerk.dev about adapting it.

Invoices and credit notes are issued for a seller in Germany only; the plugin refuses to start with any other seller country. Buyers can be in Germany (businesses, consumers, public-sector buyers), elsewhere in the EU/EEA except Italy and Poland (their clearance platforms take no EN 16931 document), Switzerland or the UK.

Versioning

Semantic versioning covers the plugin's documented interface only: its options, the events einvoice.document_issued and einvoice.issuance_blocked with their types in @normwerk/einvoice-medusa/events, the documents read with an order (einvoice_documents), the Admin and Store API routes, the "E-Invoices" admin widget, the plugin's database tables, the field mapping in the mapping reference, and the dry run's script and arguments (dry run); its report carries a format version of its own. Every other file in the package can be imported — Medusa loads subscribers and routes by their path — but is internal: paths such as invoices/* or mapping/* change in any release.

Install

Full setup — configuration, migrations, optional PDF modes — is the quickstart: about 30 minutes from a fresh create-medusa-app project to a KoSIT-validated invoice on your first fulfilled order.

Dry run: try it on your orders first

Before you turn the plugin on, run it over a period of your past orders on a staging copy — it issues nothing, and reports for every fulfillment whether it would issue the invoice, issue it with a notice, or refuse it and why:

The report names no customer. npx @normwerk/einvoice-conformance dry-run einvoice-dry-run validates the invoices' XML with the official validators and writes it as Markdown. How to run it and how to read it: dry run.

Documentation

Part of normwerk/einvoice. See that repository for:

• Quickstart
• Dry run — the plugin over your past orders, issuing nothing
• Supported countries
• Medusa field → BT/BG mapping reference
• Storage, admin widget, Store API design
• Domain glossary — every real Medusa v2 gotcha found building this

License

MIT — see LICENSE.