Refunds

About

payload-refunds adds full and partial refund handling to Payload ecommerce orders. It creates a `refunds` collection where each refund is an ordinary document, and it extends the orders collection with `refundedAmount` and `refundableAmount` fields that stay in sync with the refund records. Every amount is a whole number of minor units (cents), stored and compared as integers, and a fractional amount is refused rather than rounded. The plugin extends `@payloadcms/plugin-ecommerce` and must be registered after the orders collection exists. If that collection is absent it returns the config unchanged, so it is safe to load in any project. `refundedAmount` is recomputed from the refund records on every write, never incremented, so it cannot drift from the history. Each refund can name one or more order lines, and the units refunded across all records never exceed the units ordered. A refund is refused with a `RefundError` (HTTP 400) when its amount is zero, negative, fractional, over the refundable remainder, or when a line would be over-refunded. The `onRefund` callback runs after validation and before the record is written, so a failed call to the payment provider leaves nothing behind; returning a `reference` stores the provider's own identifier on the record. Optional restock puts refunded units back into the product or variant document the sale took them from, using compare-and-set writes with retries so a concurrent change does not get clobbered. `updateTransactionStatus` marks the matching transaction as `refunded` once the whole order is refunded, and `refundedStatus` controls whether the order status itself is written (an empty string leaves it alone, which is the right choice for partial refunds). The package ships no admin components and no runtime dependencies, not even a runtime import of `payload`, which keeps it stable across minor Payload releases. It does not invent a per-line price, because the official ecommerce plugin does not store one on an order line, so line-level caps are by quantity only. A refund record is append-only: the `beforeChange` hook refuses any operation other than `create`, so the audit trail is never edited.

Package info

Package name

payload-refunds

Latest version

1.0.0

Unpacked size

52 kB

License

MIT

Last publish

Aug 20, 2026