payload-coupons

Gives a Payload shop coupon codes with percentage and fixed discounts, scope and exclusions, usage limits and a validity window, calculated in whole minor units so that the line amounts always add up to the total.

• Works with @payloadcms/plugin-ecommerce and with any collection that holds carts and orders
• Every amount is an integer number of minor units, never a float
• A code that cannot be used is refused with a stable reason code, never converted or silently adjusted
• No runtime dependencies
• No admin components, so it survives minor releases

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-coupons

import { couponsPlugin } from 'payload-coupons'

export default buildConfig({
  plugins: [
    couponsPlugin({
      currencies: ['EUR', 'USD'],
    }),
  ],
})

Create a coupon in the admin, then ask whether it may be used:

curl -X POST /api/coupons/validate \
  -H 'Content-Type: application/json' \
  -d '{"code":"SAVE10","cartID":"6a85cce9ce631c0034f52d84"}'

{
  "valid": true,
  "discount": {
    "amount": 300,
    "code": "SAVE10",
    "coupon": "1",
    "currency": "EUR",
    "freeShipping": false,
    "lines": [{ "amount": 100, "index": 0 }, { "amount": 200, "index": 1 }],
    "type": "percentage",
    "value": 1000
  }
}

Apply it to the cart, and the cart keeps a total next to its untouched subtotal:

curl -X POST /api/carts/6a85cce9ce631c0034f52d84/apply-coupon \
  -H 'Content-Type: application/json' \
  -d '{"code":"SAVE10"}'

@payloadcms/plugin-ecommerce 3.88.0 has no discount of any kind. Its published dist contains zero occurrences of coupon, discount or promo. One third-party package exists, @wtree/payload-ecommerce-coupon, last published in March 2026; no code from it is used here.

Read from the plugin source, and the reason this package works the way it does:

The total is worked out once, on the sum of the eligible lines, and then divided. Both steps are exact integer arithmetic.

1. The rate is held in basis points, so 12.5 percent is 1250 and nothing is ever a float.
2. The total is eligible x rate / 10000, rounded half up, once.
3. Each line takes the floor of its exact share of that total.
4. The units left over are handed out one at a time, largest fractional remainder first. A tie goes to the larger line, and a tie between equal lines goes to the earlier position.
5. No line is ever given more than the line is worth, and the parts always add up to the total.

A cart of 3.33, 3.33 and 3.34 with 10 percent off gives a total of 100 cents split as 33, 33 and 34. A cart of three items of one cent each with 50 percent off gives 2 cents split as 1, 1 and 0: the third item is not rounded up to keep the split even, because that would take more than the total.

The multiplication is done in BigInt, so the split stays exact for carts far beyond the range where total x line overflows the safe integer range of a float.

The calculation is exported as computeDiscount, allocate, percentageOf and toBasisPoints, so a front end can show the same split before the cart is saved. normalizeCode uppercases and trims a code the way the plugin does.

The test suite checks this exhaustively: every total from 0 to 1000 against a three line cart, every combination of three lines drawn from a fixed set of amounts against several totals, 500 pseudo random carts of up to eight lines, and every rate from 1 to 10000 basis points against five cart shapes. In each case the parts add up to the total and no part exceeds its own line.

The same problem as sequential order numbers, and the same answer. These facts were measured on a live Payload 3.88 install while building payload-order-numbers:

So a use is not counted, it is claimed. Each redemption inserts a document whose slot is couponID#useIndex and, when a per customer limit applies, whose customerSlot is couponID#customerID#useIndex. Both are unique indexes. The insert commits on its own, outside the order's transaction, so a second order arriving at the same instant sees the claim and takes the next index. When the next index would pass the limit the code is refused. Two customers cannot both take the last use, because the database refuses the second insert.

A coupon with no limits inserts a redemption with no slot at all, so unlimited codes never contend.

A value that cannot be used is replaced by its default rather than being applied. An attempts of 0 or -5 becomes 25, and 9.9 becomes 9.

Relationship fields are only added for collections that exist in your config. A shop with no categories collection gets a coupons collection with no category scope, rather than a config that refuses to boot.

value is the basis points of a percentage coupon or the fixed amount of a fixed coupon. amount is what was actually deducted. lines records how that amount was split: index, the position of the item in items, and amount.

The redemptions collection is closed to create, read, update and delete through the API and hidden in the admin. It is written only by the plugin. The coupons collection is left on Payload's own access control, which requires a logged in user for every operation, so codes cannot be listed by the public.

Validating claims nothing. A use is claimed only when an order is created.

Every refusal carries a stable machine readable reason next to its English message. Switch on the reason, not on the text.

The full set of codes and their English messages is exported as refusalReasons, and refusalMessage returns the message for one code.

The checks run in a fixed order and the first failure is the one reported: enabled, then the validity window, then the currency, then the cart contents, then the scope, then the minimum and maximum, then the per customer limit, then the total limit.

PostgreSQL needs a large enough connection pool. Claiming a use 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. This was measured while building payload-order-numbers, which claims its numbers the same way:

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

MongoDB is not affected and needs no change.

The plugin never changes an amount you already have. The cart keeps its subtotal untouched and gains a total. The order keeps the amount it was created with, because that is what the payment provider charged; only the discount group is written. Charge the cart's total at checkout, and the order will record what the code took off. Nothing is silently rewritten, and no total ever goes below zero.

A coupon carries no uses counter. A number kept on the coupon and incremented in a hook is wrong under load, which is what the 5 of 25 above measures, so there is no such field. Uses are counted from the redemptions collection instead, with countCouponUses.

A claimed use can be lost. The claim commits before the order does. If the order then fails to save, the use is gone. Call releaseCouponRedemption to give it back:

import { releaseCouponRedemption } from 'payload-coupons'

await releaseCouponRedemption({ id: redemptionID, payload })

One coupon per cart. There is no stacking, no automatic best code, and no priority between codes. Applying a second code replaces the first.

The cart is re-checked on every save. A code that has become invalid, because the cart changed or the coupon expired, is removed from the cart and the discount goes to zero. The cart does not keep a note of why. Ask the validate endpoint for the reason.

Free shipping is data, not a shipping calculation. discount.freeShipping is exposed on the cart and the order. Nothing else is done with it, and no shipping package is touched.

Fixed amounts are never converted. A coupon with an amount in EUR is refused on a USD cart. Add an amount for each currency you sell in.

Line prices are read from the products. A cart line has no stored price, so the plugin reads priceIn{CURRENCY} from the variant, or from the product when there is no variant. A category scope reads the product as well. That is one or two reads per line; use resolveLineAmount if your prices live elsewhere.

All coupon fields are always visible in the admin. The plugin adds no admin components and no client side conditions, so the fixed amounts are shown even on a percentage coupon.

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