Coupons

About

This plugin adds coupon codes and discounts to a Payload ecommerce shop. It creates a `coupons` collection supporting percentage and fixed-amount discounts, scope (whole cart, selected products, selected categories), product and category exclusions, per-currency minimum and maximum cart amounts, a validity window, and total and per-customer usage limits. A hidden `coupon-redemptions` collection records one document per claimed use, and the plugin adds a `discount` group and a `total` field to the carts and orders collections so the cart keeps its `subtotal` next to the discounted `total`. Every amount is an integer number of minor units, never a float. Percentages are held in basis points, and the line split is computed in `BigInt` so the parts always add up to the total and no line receives more than it is worth. The plugin targets `@payloadcms/plugin-ecommerce` and any collection that stores carts and orders, with slug overrides for carts, orders, products, variants, categories, and customers. Relationship fields are added only for collections that actually exist in your config, so a shop without a `categories` collection gets a coupons collection with no category scope rather than a config that fails to boot. Three REST endpoints are exposed: `POST /coupons/validate` to check a code against a cart without claiming it, `POST /carts/:id/apply-coupon` to attach a code, and `POST /carts/:id/remove-coupon` to clear it. A code that cannot be used is refused with a stable machine-readable reason (such as `EXPIRED`, `MINIMUM_NOT_MET`, `USAGE_LIMIT_REACHED`, `CUSTOMER_LIMIT_REACHED`, `NO_ELIGIBLE_ITEMS`), and the front end is expected to switch on the reason code rather than the English text. On order creation the plugin claims a redemption and links it back to the order; `refuseOrderOnInvalidCoupon` can throw instead of saving the order without the discount. The calculation is exported as `computeDiscount`, `allocate`, `percentageOf`, and `toBasisPoints`, and `normalizeCode` uppercases and trims a code the way the plugin does, so a storefront can show the same split before the cart is saved. The package has no runtime dependencies and no custom admin components, which keeps it stable across minor Payload releases. It requires Payload 3.50 or later (peer range `>=3.50 <4`) and Node 20 or above.

Package info

Package name

payload-coupons

Latest version

1.0.0

Unpacked size

63 kB

License

MIT

Last publish

Aug 20, 2026