Order Numbers

About

The plugin gives every Payload order a short, readable reference number such as `ORD-01042`. Payload's own document identifier is not usable as an order reference: MongoDB produces a 24-character ObjectId, and PostgreSQL hands over a bare integer that starts at 1 and leaks the shop's total order count. The plugin formats a sequential number with a configurable prefix, suffix, and zero padding, and stores it on the order itself. Numbers are assigned in a `beforeChange` hook, but the claim happens through a separate reservations collection. Before an order is written, the plugin inserts the next candidate value into that collection, and the insert commits in its own transaction. A second order arriving at the same instant sees the claim and takes the next value. The unique index on the order number is the final guarantee. The author verified 25 simultaneous orders on Payload 3.88 against both PostgreSQL and MongoDB, with all numbers unique and no gaps from the reservation step itself. The plugin adds two fields to the configured orders collection: a read-only `orderNumber` text field and a hidden `orderSequence` numeric field, both unique and indexed. A hidden `order-number-reservations` collection stores claimed values and is closed to all API access. Options let you set the prefix, suffix, padding, starting value, field names, collection slugs, and the number of attempts before giving up. It works with `@payloadcms/plugin-ecommerce` and any collection named `orders` by default. Two limits are worth knowing. The sequence is ascending and unique but not gapless: a reserved value is kept even if the order then fails to save, so it is not an accounting series for invoices. On PostgreSQL the reservation insert opens a second connection while the order's transaction holds the first, so the connection pool must be sized at least twice the expected number of simultaneous orders. MongoDB is unaffected. Existing orders are not renumbered.

Package info

Package name

payload-order-numbers

Latest version

1.0.0

Unpacked size

15 kB

License

MIT

Last publish

Aug 19, 2026