{"_id":"@agilo/medusa-invoices-plugin","name":"@agilo/medusa-invoices-plugin","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agilo/medusa-invoices-plugin","version":"1.0.0","description":"Professional invoice generation plugin for MedusaJS with customizable templates and automatic PDF creation.","author":{"name":"Agilo"},"publishConfig":{"access":"public"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Agilo/medusa-invoices-plugin.git"},"homepage":"https://github.com/Agilo/medusa-invoices-plugin#readme","bugs":{"url":"https://github.com/Agilo/medusa-invoices-plugin/issues"},"exports":{"./package.json":"./package.json","./workflows":"./.medusa/server/src/workflows/index.js","./.medusa/server/src/modules/*":"./.medusa/server/src/modules/*/index.js","./modules/*":"./.medusa/server/src/modules/*/index.js","./providers/*":"./.medusa/server/src/providers/*/index.js","./*":"./.medusa/server/src/*.js","./admin":{"import":"./.medusa/server/src/admin/index.mjs","require":"./.medusa/server/src/admin/index.js","default":"./.medusa/server/src/admin/index.js"}},"keywords":["medusa","plugin","medusa-plugin-other","medusa-plugin","medusa-v2"],"scripts":{"build":"rsync -a --delete ./src/templates/ ./src/admin/templates/ && medusa plugin:build","dev":"concurrently -k -n SYNC,DEV \"yarn dev:sync\" \"yarn dev:medusa\"","dev:medusa":"medusa plugin:develop","dev:sync":"watchexec -w ./src/templates -- rsync -a --delete ./src/templates/ ./src/admin/templates/","format":"prettier . --write","format:check":"prettier . --check","lint":"eslint . --cache --cache-location .cache/eslint/ --max-warnings=0","lint:fix":"yarn lint --fix","prepublishOnly":"rsync -a --delete ./src/templates/ ./src/admin/templates/ && medusa plugin:build","test:services:up":"docker compose -f compose.test.yml up -d","test:services:down":"docker compose -f compose.test.yml down","test:services:logs":"docker compose -f compose.test.yml logs -f","test:integration:http":"TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit","test:integration:modules":"TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit","test:unit":"TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit --passWithNoTests","test:admin":"rsync -a --delete ./src/templates/ ./src/admin/templates/ && vitest run","test:admin:watch":"vitest"},"devDependencies":{"@eslint/js":"^9.39.0","@medusajs/admin-sdk":"2.13.1","@medusajs/cli":"2.13.1","@medusajs/framework":"2.13.1","@medusajs/icons":"2.13.1","@medusajs/medusa":"2.13.1","@medusajs/test-utils":"2.13.1","@medusajs/ui":"4.0.27","@swc/core":"1.5.7","@swc/jest":"^0.2.39","@testing-library/dom":"^10.4.1","@testing-library/jest-dom":"^6.9.1","@testing-library/react":"^16.3.2","@testing-library/user-event":"^14.6.1","@types/jest":"^30.0.0","@types/jsdom":"^27","@types/node":"^20.0.0","@types/react":"^18.3.2","@types/react-dom":"^18.2.25","concurrently":"^9.2.1","eslint":"^9.39.0","eslint-config-prettier":"^10.1.8","eslint-plugin-react-hooks":"^7.1.1","globals":"^17.6.0","jest":"^30.2.0","jsdom":"^27.4.0","prettier":"^3.8.3","prop-types":"^15.8.1","react":"^18.3.1","react-dom":"^18.3.1","ts-node":"^10.9.2","typescript":"^5.6.2","typescript-eslint":"^8.59.3","vite":"^5.2.11","vitest":"^4.0.17","yalc":"^1.0.0-pre.53"},"peerDependencies":{"@medusajs/admin-sdk":">=2.11.3 <3.0.0","@medusajs/framework":">=2.11.3 <3.0.0","@medusajs/icons":">=2.11.3 <3.0.0","@medusajs/medusa":">=2.11.3 <3.0.0","@medusajs/ui":">=4.0.0 <5.0.0"},"engines":{"node":">=20"},"packageManager":"yarn@4.12.0","dependencies":{"@react-pdf/renderer":"^4.3.1","@tiptap/extension-text-align":"^3.11.1","@tiptap/extension-text-style":"^3.11.1","@tiptap/pm":"^3.11.1","@tiptap/react":"^3.11.1","@tiptap/starter-kit":"^3.11.1","lucide-react":"^0.555.0"},"gitHead":"efea85f3ee4cb34c319434f6aa6e2bc2c35b8696","_id":"@agilo/medusa-invoices-plugin@1.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-W8rajUW1NuLEDvvX9r61ChajKwLvJNLkSfsT096XLNKhUDWlh2Po4MLF8eK4SxN/UEw9wdYyabr2lrjKdQ+WKg==","shasum":"b598092b8b5cf85e8b540f83291256be90f9745d","tarball":"https://registry.npmjs.org/@agilo/medusa-invoices-plugin/-/medusa-invoices-plugin-1.0.0.tgz","fileCount":50,"unpackedSize":1014277,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEEelPK2Vns8Xiv7qa5gLqZicCMzPzqeF/uvpq2q4EfhAiEAoKkGDcYV3UR95bKM00c6Fvb5X0etC2Rplwc3l+Pr+XA="}]},"_npmUser":{"name":"anteprimorac","email":"anteprimorachr@gmail.com"},"directories":{},"maintainers":[{"name":"anteprimorac","email":"anteprimorachr@gmail.com"},{"name":"josipmatichr","email":"josip@agilo.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/medusa-invoices-plugin_1.0.0_1785334227908_0.30335775224597117"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-29T14:10:27.761Z","1.0.0":"2026-07-29T14:10:28.131Z","modified":"2026-07-29T14:10:28.382Z"},"maintainers":[{"name":"anteprimorac","email":"anteprimorachr@gmail.com"},{"name":"josipmatichr","email":"josip@agilo.co"}],"description":"Professional invoice generation plugin for MedusaJS with customizable templates and automatic PDF creation.","homepage":"https://github.com/Agilo/medusa-invoices-plugin#readme","keywords":["medusa","plugin","medusa-plugin-other","medusa-plugin","medusa-v2"],"repository":{"type":"git","url":"git+https://github.com/Agilo/medusa-invoices-plugin.git"},"author":{"name":"Agilo"},"bugs":{"url":"https://github.com/Agilo/medusa-invoices-plugin/issues"},"license":"MIT","readme":"

\n \n \"Medusa\n \n

\n

\n Medusa Invoices Plugin\n

\n\n

\n Professional invoice generation for MedusaJS with customizable templates and automatic PDF creation.\n

\n
\n
\n\n## Compatibility\n\nThis plugin is compatible with versions >= 2.11.3 of `@medusajs/medusa`.\n
\n
\n\n## Description\n\nA comprehensive invoice generation plugin for MedusaJS that automatically generates PDF invoices for orders with customizable templates.\n
\n
\n\n## Features\n\n- ๐Ÿงพ Automatic invoice generation on selected triggers (e.g. Order completed)\n- ๐Ÿ“„ PDF generation with customizable templates\n- ๐ŸŽจ Template management with versioning\n- ๐Ÿ“ Integration with MedusaJS File Module\n- ๐Ÿ”ง Admin UI for configuration and manual generation\n- ๐Ÿ”” Event-based architecture\n- ๐Ÿ“Š Invoice status tracking\n
\n\n## Installation\n\n### Prerequisites\n\n- MedusaJS server\n- Configured File Module (S3, local, or other provider)\n- Node.js 20+\n\nVisit the [Quickstart Guide](https://docs.medusajs.com/learn/installation) to set up a server.\n
\nVisit the [Plugins documentation](https://docs.medusajs.com/learn/fundamentals/plugins) to learn more about plugins.\n
\nVisit the [Docs](https://docs.medusajs.com/learn/installation#get-started) to learn more about medusa system requirements.\n
\n
\n\n### Install the plugin\n\n```bash\nnpm install @agilo/medusa-invoices-plugin\n```\n\nor with yarn:\n\n```bash\nyarn add @agilo/medusa-invoices-plugin\n```\n\n
\n\n### Add to medusa-config.ts\n\n```typescript\nimport { defineConfig } from \"@medusajs/framework\";\n\nexport default defineConfig({\n projectConfig: {\n // ... other config\n },\n plugins: [\n {\n resolve: \"@agilo/medusa-invoices-plugin\",\n options: {\n // Additional options can be configured here\n },\n },\n ],\n});\n```\n\n
\n
\n\n## Configuration\n\n### 1. Configure File Module\n\nThe plugin requires a configured File Module to store generated PDF invoices. If not already configured, add one of the following to your `medusa-config.ts`:\n\n#### Example: Local File Storage\n\n```typescript\n// medusa-config.ts\nimport { defineConfig } from \"@medusajs/framework\";\n\nexport default defineConfig({\n // ...\n modules: [\n {\n resolve: \"@medusajs/medusa/file\",\n options: {\n providers: [\n {\n resolve: \"@medusajs/medusa/file-local\",\n id: \"local\",\n options: {\n // provider options...\n },\n },\n ],\n },\n },\n ],\n});\n```\n\n
\n\n#### Example: AWS S3 Storage\n\n```typescript\n// medusa-config.ts\nimport { defineConfig } from \"@medusajs/framework\";\n\nexport default defineConfig({\n // ...\n modules: [\n {\n resolve: \"@medusajs/medusa/file\",\n options: {\n providers: [\n {\n resolve: \"@medusajs/medusa/file-s3\",\n id: \"s3\",\n options: {\n file_url: process.env.S3_FILE_URL,\n access_key_id: process.env.S3_ACCESS_KEY_ID,\n secret_access_key: process.env.S3_SECRET_ACCESS_KEY,\n region: process.env.S3_REGION,\n bucket: process.env.S3_BUCKET,\n endpoint: process.env.S3_ENDPOINT,\n // other options...\n },\n },\n ],\n },\n },\n ],\n});\n```\n\nVisit the [File Module documentation](https://docs.medusajs.com/resources/infrastructure-modules/file) to learn more about file module.\n
\n
\n\n### 2. Run Database Migrations\n\nAfter installing the plugin, run migrations to create necessary database tables:\n\n```bash\nnpx medusa db:migrate\n```\n\nor with yarn:\n\n```bash\nyarn medusa db:migrate\n```\n\n
\n\nThis will create tables for:\n\n- Invoice settings\n- Invoice records\n- Store and invoice settings link\n- Order and invoice link\n
\n
\n\n### 3. Configure Invoice Settings\n\nAccess the Admin UI at `/app/settings/invoices` to:\n\n- Set up default invoice template\n- Configure company information\n- Select auto-generation triggers\n\n
\n
\n\n## API Documentation\n\n### Admin Endpoints\n\nAll admin endpoints require authentication with admin privileges.\n
\n
\n\n#### Get Invoice Settings\n\n```http\nGET /admin/invoice-settings\n```\n\nResponse:\n\n```json\n{\n \"settings\": {\n \"id\": \"invset_01\",\n \"template_id\": \"clean\",\n \"template_version\": \"1.0.0\",\n \"header_logo_type\": \"text\",\n \"header_logo_text\": \"Agilo\",\n \"header_logo_url\": null,\n \"header_content\": {},\n \"footer_content\": {},\n \"store_name\": \"Store1\",\n \"store_address\": \"Some Street 218\",\n \"store_tax_id\": \"1\",\n \"bank_account_iban\": \"12345678910\",\n \"bank_account_swift\": \"25\",\n \"auto_generate_on\": [],\n \"created_at\": \"2025-12-17T12:30:24.315Z\",\n \"updated_at\": \"2026-01-27T08:20:43.756Z\",\n \"deleted_at\": null\n },\n \"templates\": [\n {\n \"id\": \"clean\",\n \"label\": \"Clean\",\n \"version\": \"1.0.0\"\n },\n {\n \"id\": \"classic\",\n \"label\": \"Classic\",\n \"version\": \"1.0.0\"\n },\n {\n \"id\": \"compact\",\n \"label\": \"Compact\",\n \"version\": \"1.0.0\"\n }\n ],\n \"availableTriggers\": [\"order.completed\", \"order.fulfillment_created\", \"payment.captured\"]\n}\n```\n\n
\n\n#### Update Invoice Settings\n\n```http\nPOST /admin/invoice-settings\n```\n\nBody:\n\n```typescript\n{\n template_id: \"clean\",\n template_version: \"1.0.0\",\n header_logo_type: \"text\",\n header_logo_url: null,\n header_logo_text: \"Agilo\",\n header_content: {},\n footer_content: {},\n store_name: \"Store2\",\n store_address: \"Some Street 118\",\n store_tax_id: \"2\",\n bank_account_iban: \"10987654321\",\n bank_account_swift: \"24\",\n auto_generate_on: []\n}\n```\n\nResponse:\n\n```json\n{\n \"id\": \"invset_01\",\n \"template_id\": \"clean\",\n \"template_version\": \"1.0.0\",\n \"header_logo_type\": \"text\",\n \"header_logo_text\": \"Agilo\",\n \"header_logo_url\": null,\n \"header_content\": {},\n \"footer_content\": {},\n \"store_name\": \"Store2\",\n \"store_address\": \"Some Street 118\",\n \"store_tax_id\": \"2\",\n \"bank_account_iban\": \"10987654321\",\n \"bank_account_swift\": \"24\",\n \"auto_generate_on\": [],\n \"created_at\": \"2025-12-17T12:30:24.315Z\",\n \"updated_at\": \"2026-01-27T08:20:43.756Z\",\n \"deleted_at\": null,\n \"store_id\": \"store_01\"\n}\n```\n\n
\n\n#### Get Invoices by Order ID\n\n```http\nGET /admin/invoices/{order_id}\n```\n\nResponse:\n\n```json\n{\n \"invoices\": [\n {\n \"id\": \"inv_01\",\n \"status\": \"completed\",\n \"completed_at\": \"2026-01-26T10:27:31.450Z\",\n \"pdf_url\": \"http://inv_01.pdf\",\n \"template_id\": \"compact\",\n \"template_version\": \"1.0.0\",\n \"error_message\": null,\n \"order_display_id\": 1,\n \"created_by_event\": \"manual\",\n \"created_at\": \"2026-01-26T10:27:30.580Z\"\n },\n {\n \"id\": \"inv_02\",\n \"status\": \"completed\",\n \"completed_at\": \"2026-01-26T09:04:05.957Z\",\n \"pdf_url\": \"http://inv_02.pdf\",\n \"template_id\": \"compact\",\n \"template_version\": \"1.0.0\",\n \"error_message\": null,\n \"order_display_id\": 2,\n \"created_by_event\": \"manual\",\n \"created_at\": \"2026-01-26T09:04:05.620Z\"\n }\n ],\n \"count\": 2,\n \"offset\": 0,\n \"limit\": 20\n}\n```\n\n
\n\n#### Get Invoice by Order ID\n\n```http\nGET /admin/invoices/{order_id}/recent\n```\n\nResponse:\n\n```json\n{\n \"status\": \"completed\",\n \"completed_at\": \"2026-01-26T13:43:15.758Z\",\n \"pdf_url\": \"http://inv_01.pdf\",\n \"template_id\": \"compact\",\n \"template_version\": \"1.0.0\",\n \"error_message\": null,\n \"order_display_id\": 1,\n \"created_by_event\": \"manual\",\n \"created_at\": \"2026-01-26T13:43:15.514Z\"\n}\n```\n\n
\n\n#### Generate Invoice\n\n```http\nPOST /admin/invoices/{order_id}/generate\n```\n\nBody:\n\n```typescript\n{\n created_by_event: \"manual\";\n template_id: \"clean\"; // Optional\n}\n```\n\nResponse:\n\n```json\n{\n \"id\": \"inv_01\",\n \"order_id\": \"order_01\",\n \"order_display_id\": 1,\n \"status\": \"completed\",\n \"completed_at\": \"2026-01-27T09:32:12.233Z\",\n \"pdf_url\": \"http://inv_01.pdf\",\n \"template_id\": \"clean\",\n \"template_version\": \"1.0.0\",\n \"settings_snapshot\": {\n \"store_name\": \"Store1\",\n \"header_logo\": {\n \"url\": null,\n \"text\": \"Agilo\",\n \"type\": \"text\"\n },\n \"template_id\": \"clean\",\n \"store_tax_id\": \"1\",\n \"store_address\": \"Some Street 218\",\n \"footer_content\": {},\n \"header_content\": {},\n \"template_version\": \"1.0.0\",\n \"bank_account_iban\": \"12345678910\",\n \"bank_account_swift\": \"25\"\n },\n \"error_message\": null,\n \"created_by_event\": \"manual\",\n \"created_at\": \"2026-01-27T09:32:11.896Z\",\n \"updated_at\": \"2026-01-27T09:32:12.234Z\",\n \"deleted_at\": null\n}\n```\n\n
\n\n### Store Endpoint\n\nCustomers can access and download their own invoice PDFs.\n
\n
\n\n#### Get Customer Invoice PDF\n\n```http\nGET /store/invoices/{order_id}.pdf\n```\n\nResponse:\n\n- returns a PDF file stream\n\n
\n\n**Note:** Customers can only access invoices for their own orders. Authentication is required.\n
\n
\n\n## Admin UI Guide\n\n### Invoice Settings\n\n#### Accessing Invoice Settings\n\nNavigate to **Settings โ†’ Invoices** in the Medusa Admin dashboard.\n
\n
\n\n#### Settings Page Features\n\nThe settings page allows you to:\n\n1. **Select Active Template**\n - Choose which template to use for invoice generation\n - Preview templates before activating (with dummy or selected order data)\n\n ![Invoice Settings - Select Active Template](https://github.com/user-attachments/assets/1cc308c4-f904-444b-b118-1fba83f568ff)\n\n2. **Input Company Information**\n - Configure store name, address, header, footer...\n - This information appears on all generated invoices\n\n ![Invoice Settings - Company Information](https://github.com/user-attachments/assets/239e5283-9086-44df-a0f4-af8be7270139)\n\n3. **Select Active Auto Generation Triggers**\n - Choose the trigger on which the invoice is generated\n - Possible triggers: Order completed, Fulfillment created, Payment captured\n\n### Invoice Widget\n\n#### Accessing Invoice Widget\n\nNavigate to **Orders โ†’ Select one order** in Medusa Admin dashboard.\n
\n
\n\n#### Invoice Widget Features\n\nThe widget allows you to:\n\n1. View latest invoice data\n2. Manually generate invoice\n3. View invoice status\n - Queued (waiting for invoice generation)\n - Generating (invoice is being generated)\n - Completed (invoice was successfully generated)\n - Failed (invoice generation was unsuccessful)\n\n ![Invoice Widget - Invoice Status](https://github.com/user-attachments/assets/4066e873-62f0-4ed3-af64-279252fe0013)\n\n4. View invoice history\n - List of all invoices generated for that order\n - Possible to filter by particular attributes\n\n ![Invoice Widget - Invoice History](https://github.com/user-attachments/assets/5c6f87e4-ed8b-4fdc-a9f6-763131c7aa33)\n\n## Events\n\nThe plugin emits events that you can subscribe to for custom workflows.\n
\n
\n\n### invoice.generated\n\nEmitted when an invoice is successfully generated.\n\n**Payload (`event.data`):**\n\n```typescript\n{\n invoice_id: string,\n order_id: string,\n order_display_id: number,\n pdf_url: string,\n template_id: \"clean\" | \"classic\" | \"compact\",\n template_version: string,\n completed_at: Date | string\n}\n```\n\n
\n\n### invoice.failed\n\nEmitted when invoice generation fails.\n\n**Payload (`event.data`):**\n\n```typescript\n{\n order_id: string,\n error_message: string\n}\n```\n\n
\n\n### How to Subscribe to Events\n\nCreate a subscriber in your Medusa project:\n\n```typescript\n// src/subscribers/invoice.ts\nimport { SubscriberArgs, type SubscriberConfig } from \"@medusajs/framework\";\n\ntype InvoiceGeneratedPayload = {\n invoice_id: string;\n order_id: string;\n order_display_id: number;\n pdf_url: string;\n template_id: string;\n template_version: string;\n completed_at: string;\n};\n\nexport default async function invoiceHandler({\n event,\n container,\n}: SubscriberArgs) {\n const { name, data } = event;\n console.log(`invoices: subscriber triggered for event ${name}`);\n\n // Your custom logic here\n}\n\nexport const config: SubscriberConfig = {\n event: [\"invoice.generated\"],\n};\n```\n\n
\n\n## Contributing\n\nWe welcome contributions and feedback.\nTo get involved, [open an issue](https://github.com/Agilo/medusa-invoices-plugin/issues) or [submit a pull request](https://github.com/Agilo/medusa-invoices-plugin/pulls) on [GitHub โ†’](https://github.com/Agilo/medusa-invoices-plugin)\n","readmeFilename":"README.md","_rev":"1-6abb3fa1738f0ad10b417ffd7ee771ff"}