Fulfillment

About

Extends the orders collection from `@payloadcms/plugin-ecommerce` with the states a real shop needs between payment and delivery, plus a record of how an order got there. The official plugin gives an order four statuses (processing, completed, cancelled, refunded). This package appends four more (pending-payment, on-hold, shipped, failed) after the originals, without removing or reordering them, so existing orders keep working. `fulfillmentPlugin` sits after `ecommercePlugin` in the plugins array and extends whatever orders collection it finds, merging its states into the existing status select and adding array fields for history and notes plus a tracking number and carrier. It has no runtime dependency on `payload` and ships no admin components, which keeps it stable across minor releases. A `beforeChange` hook writes each transition (from, to, at, by, byEmail) into the history field. That field is closed to direct API writes (`create: false, update: false`), so no request can forge or edit an entry; only the hook can. `guardTransitions` refuses a status change the transition map does not allow and answers with HTTP 400 through an exported `InvalidTransitionError` that carries `status` and `isPublic`. The default map covers all eight states; passing `transitions` replaces it wholesale, and a state that is not a key of the map is never refused, so custom states do not lock the shop out. `carriers` turns the carrier field into a select, `trackingStates` controls which states show the tracking fields in the admin panel (default shipped and completed), and `internalAccess` defaults to denying the order's own customer while letting staff through. The history lives as an array on the order document rather than a separate collection, chosen because the entry is appended in the same write and transaction as the order update. The tracking fields hide via `admin.condition` but still exist in the database and the API response. The package is built and tested against Payload 3.88 and `@payloadcms/plugin-ecommerce` 3.88.0, with a peer range of `payload >=3.50 <4`.

Package info

Package name

payload-fulfillment

Latest version

1.0.0

Unpacked size

32 kB

License

MIT

Last publish

Aug 20, 2026