Stock Reservation

About

This plugin sits on top of `@payloadcms/plugin-ecommerce` and fixes two gaps in its checkout flow. The official plugin reads availability in `initiatePayment` and decrements stock in `confirmOrder`, but writes nothing in between, so two shoppers can both pass validation on the last unit. It also skips variant stock and price checks entirely, because the variant branch sits inside a condition that requires the item to have no variant. Both problems let stock go negative after payment. `stockReservationPlugin` wraps the `post /payments/:adapter/initiate` and `post /payments/:adapter/confirm-order` endpoints rather than replacing them. Before initiation it re-reads the cart, validates every line against recorded stock minus live holds, and writes a hold outside the request transaction so competing requests see it immediately. Holds on the same product or variant are ranked oldest first, with identifier tie-breaking, and a hold keeps its stock only if the running total up to and including it fits inside recorded stock. On confirmation the original handler runs first, then the cart's holds are released. The plugin adds a single `stock-holds` collection with indexed `cart`, `stockCollection`, `stockDocument`, and `expiresAt` fields, and nothing is added to products, variants, carts, or orders. The collection is closed to API access and hidden in the admin panel. A `/stock-reservation/release-expired` endpoint deletes expired holds and accepts either a signed-in user or a `Bearer` secret. `sweepOnCheckout` deletes expired holds for the current cart at the start of every checkout, so no scheduler is required. Options include `ttlSeconds` (default 900), `defaultCurrency`, `refuseNegativeInventory`, `holdScanLimit`, and slug overrides for the carts, products, variants, and holds collections. The plugin must be listed after `ecommercePlugin`, and it logs a clear error on startup if it finds no checkout endpoints to wrap. It has no runtime dependencies and no admin components, which keeps it stable across minor Payload releases. It is verified against Payload 3.88.0 and requires Payload 3.88 or newer.

Package info

Package name

payload-stock-reservation

Latest version

1.0.0

Unpacked size

40 kB

License

MIT

Weekly downloads

144

Last publish

Aug 21, 2026