Invoices medusa

Name: Invoices medusa
Author: Webbers

Add invoices to Medusa v2

npm install @webbers/invoices-medusa

@webbers/invoices-medusa

A Medusa v2 plugin that automatically generates sequential PDF invoices for orders and credit notes for refunds. PDFs are uploaded to your private file storage bucket and served to customers and admins via presigned URLs.

Requirements

Medusa
A configured File Module Provider (e.g. S3/R2) with private bucket support

Installation

pnpm add @webbers/invoices-medusa

Configuration

1import { defineConfig } from "@medusajs/framework/utils"
2
3export default defineConfig({
plugins: [
  {
    resolve: "@webbers/invoices-medusa",
    options: {
      // Optional: locale to fall back to when order.metadata.locale is absent
      // or not a supported value. Defaults to "nl".
      defaultLocale: "en",
11
      addressInfo: {
        // Optional: SVG string or base64 data URL shown in the default header
        companyLogo: "<svg>...</svg>",
        // Optional: rendered width of the logo in points (default: 110)
        companyLogoWidth: 110,
17
        companyName: "Acme B.V.",
19
        // Receives the i18n countries object for the resolved locale so you
        // can include a translated country name in the address block.
        address: (countries) =>
          `Streetname 1\n1234 AB Amsterdam, ${countries.nl}`,
24
        cocNumber: "12345678",
        vatNumber: "NL123456789B01",
        iban: "NL00BANK0123456789",
        email: "billing@example.com",
      },
30
      // Optional: accent colors used in table headers
      colors: {
        background: "#004534", // header cell fill (default: #000)
        text: "#ffffff",       // header cell text (default: #fff)
      },
36
      // Optional: pdfmake Content rendered as the page header.
      // Overrides the default logo header when provided.
      header: {
        table: {
          widths: ["*"],
          body: [[{ text: "Acme B.V.", fontSize: 18, alignment: "center" }]],
        },
        layout: "noBorders",
      },
46
      // Optional: pdfmake Content rendered as the page footer.
      footer: {
        table: {
          widths: ["*"],
          body: [[{ text: "acme.com", alignment: "center" }]],
        },
        layout: "noBorders",
      },
    },
  },
],
58})

Configuration reference

Option	Type	Required	Description
		No	Fallback locale when is absent or invalid. Defaults to .
		Yes	Company name shown on the invoice.
		Yes	Function returning the company address. Receives the i18n country name map for the resolved locale.
		Yes	Chamber of Commerce number.
		Yes	VAT registration number.
		Yes	Bank account number.
		Yes	Billing contact e-mail.
		No	SVG string or data URL used in the default header.
		No	Rendered logo width in points.
		No	Table header fill color (CSS hex).
		No	Table header text color (CSS hex).
		No	pdfmake content block rendered as page header. Replaces the default logo header.
		No	pdfmake content block rendered as page footer.

How it works

Invoice lifecycle

Fulfillment created — the subscriber fires , which:
- Creates a debit invoice record with an auto-incremented
- Links it to the order via the link table
- Generates the PDF and uploads it to the private storage bucket
- Stores the file ID in
Refund processed — follows the same steps for a credit invoice, referencing the original debit invoice as its parent.
Download requested — the API route resolves to a presigned download URL via and redirects the client. Invoices without a stored PDF (created before this feature) are generated on-demand as a fallback.

Invoice numbering

is a PostgreSQL auto-increment sequence. Voided invoices (created by workflow compensation on failure) preserve their sequence number to avoid gaps.

Localization

The PDF language is determined by . The value is validated against the list of supported locales; if it is absent or unrecognised, from the plugin config is used.

Supported locales:

Value	Language
	Dutch
	Dutch (Belgium) — uses Dutch translations
	English
	German
	French
	Italian

Set the locale on an order at creation time:

1await orderModuleService.updateOrders(orderId, {
2  metadata: { locale: "en" },
3})

API routes

Admin

GET /admin/orders/:id/invoice/:invoice_id

Requires admin authentication. Redirects to a presigned download URL for the invoice PDF.

Store

GET /store/orders/:id/invoice

Requires customer authentication. Returns the debit invoice PDF for the order. The order must belong to the authenticated customer.

Workflows

The workflows can be called directly from your own subscribers, jobs, or API routes.

Creates a debit invoice, links it to an order, and generates + uploads the PDF.

1import { createInvoiceWorkflow } from "@webbers/invoices-medusa/workflows"
2
3await createInvoiceWorkflow(container).run({
4  input: { order_id: "order_01J..." },
5})

Creates a credit invoice for a refund.

1import { createCreditInvoiceWorkflow } from "@webbers/invoices-medusa/workflows"
2
3await createCreditInvoiceWorkflow(container).run({
4  input: {
5    order_id: "order_01J...",
6    resource_id: "refund_01J...",      // refund ID used as resource_id
7    parent_invoice_id: "inv_01J...",   // optional: the debit invoice this offsets
8  },
9})

Generates an invoice PDF on-demand and returns it as a base64 string. Useful for attaching to notification emails.

1import { generateInvoicePdfWorkflow } from "@webbers/invoices-medusa/workflows"
2
3const { result } = await generateInvoicePdfWorkflow(container).run({
4  input: {
5    order_id: "order_01J...",
6    invoice_id: "inv_01J...", // optional; omit to generate the debit invoice
7  },
8})
9
10// result.fileName  — e.g. "invoice-42.pdf"
11// result.data      — base64-encoded PDF

Backfill script

To generate and upload PDFs for invoices created before file storage was introduced:

1# Dry run (default) — shows what would be processed
2pnpm medusa exec ./src/scripts/backfill-invoice-pdf-urls.ts
3
4# Execute
5pnpm medusa exec ./src/scripts/backfill-invoice-pdf-urls.ts -- dry_run=false
6
7# Smaller batches if memory is a concern
8pnpm medusa exec ./src/scripts/backfill-invoice-pdf-urls.ts -- dry_run=false batch_size=10