payload-order-numbers

Gives every Payload order a short, human readable number such as ORD-01042, assigned in sequence and unique under concurrency, so that a customer and a shop can refer to the same order out loud.

• Works with @payloadcms/plugin-ecommerce and with any collection that holds orders
• Verified on Payload 3.88 against both PostgreSQL and MongoDB
• No runtime dependencies
• No admin components, so it survives minor releases

Install

Requires Payload 3.88 or newer and @payloadcms/plugin-ecommerce 3.88 or newer. Verified against Payload 3.88.0 with the official plugin installed.

pnpm add payload-order-numbers

import { orderNumbersPlugin } from 'payload-order-numbers'

export default buildConfig({
  plugins: [
    orderNumbersPlugin({
      prefix: 'ORD-',
      padding: 5,
      startAt: 1000,
    }),
  ],
})

The first order becomes ORD-01000, the next ORD-01001, and so on.

What was measured

A Payload document identifier is not something you can read to a customer over the phone. Measured on a live Payload 3.88 install:

Database	What an order id looks like
MongoDB	6a85cce9ce631c0034f52d84, a 24 character ObjectId
PostgreSQL	1, 2, 3, an auto incrementing integer

The MongoDB identifier is unusable as an order reference. The PostgreSQL identifier is readable, but it starts at 1, carries no prefix, and tells anyone who sees it exactly how many orders the shop has taken.

Why the obvious approach does not work

The first design read the highest existing number and added one, inside a beforeChange hook. Measured with 25 orders created in the same instant:

Design	Orders that succeeded	Why
beforeChange, highest plus one	5 of 25	every request reads the same highest value inside its own transaction
afterChange with retry	3 of 25	retrying inside the same aborted transaction cannot succeed
Reservation committed separately	25 of 25	each number is claimed in its own transaction and is immediately visible

No design ever produced a duplicate. The unique index held in every run. The failures were refusals, not corruption.

How it works now

Before an order is written, the plugin claims the next free value by inserting it into a small reservations collection. That insert commits on its own, so a second order arriving at the same moment sees the claim and takes the next value. The unique index on the order number is the final guarantee, not the first line of defence.

Verified with 25 orders created simultaneously:

Database	Orders with a number	Unique	Gaps
MongoDB	25 of 25	25 of 25	none
PostgreSQL	25 of 25	25 of 25	none

Options

Option	Default	Meaning
attempts	50	How many values to try before giving up. Each attempt is one insert
disabled	false	Stops assigning numbers but keeps the fields, so the database keeps its shape
fieldName	'orderNumber'	Field holding the formatted number
ordersSlug	'orders'	Slug of the orders collection
padding	0	Minimum width of the numeric part, left padded with zeros
prefix	''	Text placed before the number
reservationsSlug	'order-number-reservations'	Collection holding claimed values
sequenceFieldName	'orderSequence'	Numeric field the sequence is read from
startAt	1	Value given to the first order
suffix	''	Text placed after the number

A value that cannot be used is replaced by its default rather than being applied. A negative padding becomes 0, a startAt of 0 becomes 1, and 4.9 becomes 4. Nothing is silently reinterpreted: -5 never becomes 5.

What it adds to your database

Collection	Field	Type	Notes
your orders collection	orderNumber	text	unique, indexed, read only in the admin sidebar
your orders collection	orderSequence	number	unique, indexed, hidden
order-number-reservations	sequence	number	unique, indexed. Collection hidden, no API access

The reservations collection is closed to create, read, update and delete through the API. It is written only by the plugin.

Honest limits

PostgreSQL needs a large enough connection pool. Claiming a number opens a second connection while the order's own transaction holds the first. With the pg default of 10, ten simultaneous orders exhaust the pool and the eleventh waits forever. Measured exactly:

Simultaneous orders	Result with the default pool of 10
2, 4, 6, 8, 10	all succeed
15	3 succeed, the rest time out

Set the pool to at least twice the number of orders you expect in the same instant:

postgresAdapter({
  pool: { connectionString: process.env.DATABASE_URI, max: 60 },
})

MongoDB is not affected and needs no change.

Numbers can have gaps. A claimed value is not returned if the order then fails to save. The sequence stays ascending and unique, but it is not a gapless accounting series. If you need one for invoices, that is a different guarantee and belongs in a different package.

Existing orders are not renumbered. The plugin only assigns a number when an order is created. Orders already in the database keep an empty orderNumber.

Under extreme load the order still saves. If all attempts are exhausted the order is written without a number and an error is logged. Losing a sale is worse than losing a label.

License

MIT. Copyright George Vasiliades, https://github.com/Poseidonas