Configuration

Every field of EinvoiceModuleOptions — the object you pass under options when you resolve @normwerk/einvoice-medusa in medusa-config.ts's plugins array. Generated directly from packages/einvoice-medusa/src/modules/einvoice/service.ts at revision 5ab878035219 — the doc comment on each field below is the same one a contributor reading the source sees, not a separate description that can fall out of sync with it.

See the quickstart for a complete, minimal medusa-config.ts.

Source

This page is generated from packages/einvoice-medusa/src/modules/einvoice/service.ts at the pinned revision 5ab878035219. Edit it there, not here.

seller (required)

The merchant's own party details — every invoice this plugin builds uses them as the seller (CommerceInvoiceInput.seller). Besides the name, country, city and post code, the plugin refuses to start without the seller's VAT-ID (vatIdentifier, BT-31), street (addressLine1 — the street and house number, or a PO box), electronic address with its scheme (electronicAddress, electronicAddressScheme) and contact (contact: name, telephone, email).

readonly seller: CommerceParty;

defaultProfile (optional)

Passed straight through to selectProfile's own preferredProfile (@normwerk/einvoice-commerce) — the merchant's preference for an ordinary B2B invoice. Never overrides a B2G buyer (a Leitweg-ID buyer reference forces XRECHNUNG regardless — selectProfile's own rule, not re-implemented here). Defaults to selectProfile's own default ("EN16931") when omitted.

readonly defaultProfile?: EInvoiceProfileName;

payment (required)

BG-16, payment instructions — how the buyer pays the seller: a payment means code and, for a bank transfer, an IBAN. Required: every document this plugin builds declares the XRechnung 3.0 CIUS, whose BR-DE-1 makes payment instructions mandatory whichever profile selectProfile resolves, even though CommerceInvoiceInput.payment is optional in its own type. terms (BT-20) is not in the data model yet; buildInvoice reports it as a warning rather than dropping it silently.

readonly payment: {
    readonly means: PaymentMeansCode;
    readonly iban?: string;
    readonly terms?: string;
  };

standalone (optional)

A PDF to embed the XML into. The plugin calls basePdf once per document with the built Invoice — the same object it serializes to XML — so the PDF can show exactly the number (BT-1) and amounts the XML carries; the result is embedded as PDF/A-3 (embedInvoiceInPdfA3). Use your own invoice template, another plugin, or renderInvoicePdf from @normwerk/einvoice-pdfa. Returning undefined — or omitting the option — produces XML only.

The PDF is embedded as it is — nothing repairs it — so it is checked first (checkPdfAEligibility): an encrypted PDF, or one with a font it does not embed, cannot become PDF/A. The document is then issued as XML alone and carries a notice saying why (PDF_ENCRYPTED, PDF_FONT_NOT_EMBEDDED, pdf.ts).

readonly standalone?: {
    readonly basePdf?: (
      invoice: Invoice,
    ) => Promise<Uint8Array | undefined> | Uint8Array | undefined;
  };

vatIdVerifier (optional)

Checks a buyer's VAT-ID, typically against the EU's VIES service. buildInvoice refuses category K (an intra-EU supply) without a positive check; the subscribers call verify() before building the document (ADR-003: I/O happens before buildInvoice, never inside it) and pass the result on as its evidence. The plugin ships no VIES client — implement VatIdVerifier from @normwerk/einvoice-commerce (see docs/quickstart-medusa.md). Omitted, an order that would be category K is refused, unless the merchant declares on the order that the VAT-ID was confirmed another way (order.metadata.regime_override, kind intra-eu-confirmed).

readonly vatIdVerifier?: VatIdVerifier;

ossRegistered (optional)

Whether the merchant is registered for the EU's OSS (one-stop shop) scheme — a fact about the seller that holds for every order (docs/tax-semantics.md row 7). For a distance sale to a consumer in another EU country, decideVatCategory also needs the destination country's rate on the order (order.metadata.oss_rate_override); this option covers only the registration and never bypasses that check. Defaults to false.

readonly ossRegistered?: boolean;

now (optional)

The clock for a document's issue date and for vatIdVerifier.verify()'s now argument. Defaults to () => new Date(). Meant for tests: the e2e stand fixes it so every document carries the same date on every run.

readonly now?: () => Date;