Invoices

About

payload-invoices issues numbered invoices and credit notes for orders created with @payloadcms/plugin-ecommerce. It attaches to whatever collection holds your orders and adds two collections of its own: one for the invoice documents and one for the per-series, per-year counters that back the numbering. The headline property is a gapless sequence. A number is claimed with a compare-and-set write against a single counter document, and that write happens inside the caller's own transaction. If the invoice document fails to save, the transaction rolls the counter back with it, so a document that is never written leaves no gap. A unique index on the number is the final guarantee against duplicates. The caveat is that this only holds for documents the plugin writes, and on PostgreSQL (or MongoDB with a replica set) where Payload runs each request in a transaction. Every invoice stores a frozen snapshot. Line prices are read from the product or variant in the order's currency at the moment of issuing and then locked into the document, so a later price change cannot reach back and alter a past invoice. All amounts are integers of minor units from input to storage, and the plugin refuses a fractional amount rather than rounding it. When the resolved lines do not add up to the charged amount, it can either insert a labelled adjustment line or throw, depending on configuration. The PDF is produced by a roughly 200-line encoder that ships with the package, with no runtime dependencies and no runtime import of payload. The default number format is `SERIES-YEAR-00001`, reset yearly by default, and credit notes get their own series. Invoices are issued by calling `issueInvoice` or `issueCreditNote`, or automatically through an `afterChange` hook tied to order statuses. The PDF for a document is served at `GET /api/invoices/:id/pdf`. There are no admin UI components, which keeps it stable across minor Payload releases.

Package info

Package name

payload-invoices

Latest version

1.0.0

Unpacked size

75 kB

License

MIT

Last publish

Aug 20, 2026