Быстрый старт

Шаг 1: Установка

Установите пакет через Extras → Installer. С 1.1.0-beta1 Package Manager сам откажет на несовместимых версиях; для уверенности обновите зависимости заранее:

Пакет	Минимум	Для чего нужен
PHP	8.2	Весь backend компонента
MODX	3.0.0	Ядро
MiniShop3	1.13.0-beta1	Response envelope + RateLimitStoreFactory в MS3 Router
pdoTools	3.0.0	FQN ModxPro\PdoTools\Fetch в сниппете ms3PromoCodeForm
VueTools	1.2.0	@vuetools/useTheme + ключ vuetools/theme в Import Map

Phinx-миграции отработают автоматически и создадут таблицы modx_ms3_promo_codes и modx_ms3_promo_code_usages.

Шаг 2: Создание первого кода

1. В меню MODX откройте Компоненты → Промо-коды → Управление кодами.
2. Нажмите Новый код.
3. Заполните форму:
   • Код — WELCOME10.
   • Название — обязательное поле, например Приветственная скидка 10%.
   • Тип скидки — percent. Подпись соседнего поля зависит от типа: Процент для percent, Сумма для fixed.
   • Процент — 10.
   • Область применения — all (на всю корзину).
   • Активен — да.
4. Сохраните.

Подробнее об опциях — Управление кодами.

Шаг 3: Добавление формы в шаблон корзины

В шаблоне страницы корзины (например, tpl.msCart или собственный чанк) добавьте вызов сниппета:

{'!ms3PromoCodeForm' | snippet}

Сниппет выведет форму с полем ввода и кнопкой «Применить». Стили подключит системная настройка ms3promocode.frontend_assets_preset.

Шаг 4: Проверка

1. Добавьте товар в корзину и перейдите на страницу корзины — там появится форма промо-кода.
2. Введите WELCOME10 и нажмите «Применить». Цены позиций уменьшатся на 10%, итог пересчитается.
3. Оформите заказ.
4. В админке откройте заказ → вкладка Промо-код покажет применённый код.
5. В разделе Компоненты → Промо-коды → Аналитика появится запись о применении.

Шаг 5 (опционально): Автосброс при отмене заказа

Чтобы применение откатывалось при переходе заказа в «Отменён» (счётчик used_count уменьшится на 1):

1. Система → Настройки → namespace ms3promocode.
2. Найдите ms3promocode.cancel_statuses.
3. Укажите ID статусов через запятую. В стандартной MiniShop3 это 5 («Отменён»); если на магазине добавлены свои — впишите нужные ID.

При обратном переходе из этих статусов применение восстанавливается автоматически.

Шаг 6 (опционально): Блокировка изменений по статусу

Чтобы менеджер не мог применить или снять код у заказа в определённых статусах:

1. Система → Настройки → ms3promocode.lock_statuses.
2. Укажите ID статусов через запятую, например 4,5 (в стандартной MiniShop3: 4 — «Отправлен», 5 — «Отменён»).

В этих статусах вкладка Промо-код в карточке заказа работает только на просмотр.

Что дальше

• Управление кодами — все опции редактора (даты действия, лимиты, минимальная сумма, правила).
• Шаблон формы — как переопределить чанк, какие data-атрибуты доступны.
• Web API — для интеграции с собственным фронтендом / SPA.
• Аналитика — KPI и журнал использований.

Типовые сценарии

Скидка на конкретный бренд

1. Создайте код APPLE15, тип percent, размер 15.
2. Область применения — matching (только подпадающие позиции).
3. На вкладке Правила в секции Бренды выберите нужный бренд.
4. Сохраните.

Скидка распределится пропорционально по позициям этого бренда.

Скидка только при заказе от 5000 ₽

1. Создайте код BIG500, тип fixed, размер 500.
2. В поле Мин. сумма заказа укажите 5000.
3. Сохраните.

Если корзина меньше 5000 ₽, покупатель увидит сообщение «Сумма заказа меньше требуемого минимума (5 000 ₽)».

Пакетная генерация кодов для рассылки

1. Компоненты → Промо-коды → Управление кодами, нажмите Новый код.
2. В переключателе Способ задания выберите По маске.
3. Маска: WINTER-####-??.
4. Количество: 1000.
5. Задайте тип, размер и период действия.
6. Сохраните — пакет создаст 1000 уникальных кодов вида WINTER-4729-KM.