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 ea6b031ccb33 — 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 ea6b031ccb33. Edit it there, not here.

seller (required)

The merchant's own party details — every invoice this plugin builds uses this as seller (CommerceInvoiceInput.seller). Includes vatIdentifier (BT-31); there is no separate top-level "VAT-ID" field even though the task description names it alongside "seller" — CommerceParty already carries it, and a second field would just be a second place for the same fact to go stale.

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 should pay the seller (bank transfer details), the same way seller itself is merchant-level config rather than something read off an order. Found mandatory for every invoice this plugin builds by a real KoSIT rejection (BR-DE-1, T-071's own e2e proof) — not anticipated when T-070 first scoped this module's options, since buildInvoice's own specificationIdentifier always targets the XRechnung 3.0 CIUS regardless of which profile selectProfile resolves, so BG-16 is never actually optional the way it looks from CommerceInvoiceInput.payment's own type (?:) alone.

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

integration (optional)

T-072: opt into "on top of a PDF plugin" mode (plan-v0.1 §4.6) instead of this plugin's own standalone numbering. "webbers" is the one plan-v0.1 names by product (@webbers/invoices-medusa) — when set, subscribers reuse their invoice's own display_id as this plugin's own document number instead of allocating one via NumberingStore/EinvoiceCounter ("не дублировать нумерацию"), and embed this plugin's XML into their PDF as PDF/A-3 when one is available (integrations/webbers.ts). Omitted (the default) keeps T-071's standalone behavior unchanged — this plugin still works with no PDF plugin installed at all, matching plan-v0.1's own "Standalone" mode.

readonly integration?: {
    readonly kind: "webbers";
    /** How long a subscriber waits for their invoice to appear before giving up, ms — real, necessary
     * because their own workflow defines no `createHook()` (`integrations/webbers.ts`'s own doc comment).
     * Defaults to `waitForWebbersInvoice`'s own default (10s) when omitted. */
    readonly waitForInvoiceMs?: number;
    readonly pollIntervalMs?: number;
  };

standalone (optional)

T-073: standalone mode's own way to satisfy plan-v0.1 §4.6's second bullet ("XML + PDF/A-3 из переданного PDF") when integration is omitted entirely — Webbers mode has its own PDF source (integrations/webbers.ts), but standalone mode has no third-party workflow to poll, so the merchant supplies a base PDF themselves, generated however they already generate invoice PDFs today (their own template renderer, a different plugin, @normwerk/einvoice-pdfa's own renderInvoicePdf when they have none). Called once per document with the built Invoice (same object serializeCii itself serializes) rather than the raw Medusa order, so a real implementation can render exactly what BT-1 (Invoice.number) etc. the XML will actually carry, not a value it would otherwise have to re-derive. Returning undefined (the default when this whole option is omitted) keeps this plugin's original standalone behavior — pure XML, no PDF at all.

Ignored entirely when integration is set. Same as Webbers mode (T-072, its own e2e proof), the PDF this returns is embedded as-is by embedInvoiceInPdfA3 (T-030) — it does not repair a PDF that isn't already PDF/A-eligible (e.g. one using non-embedded standard fonts); that is embedInvoiceInPdfA3's own already-documented limitation (D-20 "Path 2"/render-invoice.ts's own doc comment), not something this option works around.

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