Coupons

Описание

Плагин добавляет купоны со скидками в магазин на Payload ecommerce. Создаётся коллекция `coupons` с поддержкой процентов и фиксированных сумм, ограничением области действия (вся корзина, отдельные товары, категории), исключениями товаров и категорий, минимальной и максимальной суммой корзины в разрезе валют, периодом действия и лимитами использования (общий и на покупателя). Скрытая коллекция `coupon-redemptions` хранит по одному документу на каждый факт применения купона. К коллекциям корзин и заказов добавляются поле `discount` и поле `total`, так что в корзине сохраняется `subtotal` рядом со итоговой суммой с учётом скидки. Все суммы хранятся целыми числами в минорных единицах, без чисел с плавающей точкой. Проценты указываются в базисных пунктах, а распределение по строкам корзины считается через `BigInt`, поэтому части всегда сходятся к общей сумме и ни одна строка не получает больше, чем положено. Плагин работает с `@payloadcms/plugin-ecommerce` и любыми коллекциями для корзин и заказов, с переопределением slug для корзин, заказов, товаров, вариантов, категорий и покупателей. Поля связей добавляются только для тех коллекций, которые есть в конфиге: если в магазине нет коллекции `categories`, в купонах просто не будет области действия по категориям, а не сломанная конфигурация. Доступны три REST-эндпоинта: `POST /coupons/validate` проверяет код применительно к корзине без его использования, `POST /carts/:id/apply-coupon` привязывает код, а `POST /carts/:id/remove-coupon` снимает его. Если код нельзя использовать, ответ содержит стабильный машинно-читаемый код причины (`EXPIRED`, `MINIMUM_NOT_MET`, `USAGE_LIMIT_REACHED`, `CUSTOMER_LIMIT_REACHED`, `NO_ELIGIBLE_ITEMS` и другие). Фронтенд должен ориентироваться на этот код, а не на текст. При создании заказа плагин фиксирует использование купона и связывает его с заказом. Опция `refuseOrderOnInvalidCoupon` может выбрасывать ошибку вместо сохранения заказа без скидки. Расчётная логика экспортируется как `computeDiscount`, `allocate`, `percentageOf` и `toBasisPoints`, а `normalizeCode` приводит код к верхнему регистру и обрезает пробелы так же, как плагин, чтобы фронтенд мог показать распределение скидки ещё до сохранения корзины. Пакет не имеет runtime-зависимостей и кастомных админ-компонентов, поэтому остаётся стабильным при обновлениях Payload. Требуется Payload 3.50 или новее (peer-диапазон `>=3.50 <4`) и Node 20 или выше.

О пакете

Имя пакета

payload-coupons

Последняя версия

1.0.1

Размер

64 кБ

Лицензия

MIT

Загрузок в неделю

4

Последняя публикация

21 авг. 2026 г.