При попытке реализовать программу лояльности на базе Kill Bill разработчики быстро обнаруживают, что в платформе нет готового модуля «бонусных баллов» — и начинают искать, какие штатные механизмы биллинга можно адаптировать под кэшбэк, скидки за стаж и накопительные кредиты. Kill Bill — это open-source биллинговая платформа, изначально спроектированная для подписочных и usage-based моделей монетизации, поэтому лояльность в ней строится из существующих примитивов: кредитов на счёте, купонов, кастомных фаз каталога и плагинов.
В этой статье разберём, какие инструменты Kill Bill реально подходят для бонусной механики, где проходят границы штатных возможностей и когда без собственного плагина не обойтись. Материал ориентирован на разработчиков и архитекторов, которые интегрируют биллинг с CRM или маркетинговой платформой.
Что Kill Bill умеет «из коробки» для лояльности
Ядро Kill Bill оперирует понятиями аккаунта, подписки, инвойса и платежа. Прямой сущности «бонусный счёт» в нём нет, но есть несколько механизмов, которые функционально покрывают типовые сценарии программ лояльности.
- 💳 Кредиты на аккаунте (account credits) — денежный остаток, который автоматически зачитывается при генерации следующего инвойса. Подходит для кэшбэка в денежном эквиваленте.
- 🎟️ Скидочные фазы каталога — в каталоге можно описать план с фазой
discount, где цена снижена на фиксированный срок. Это основа для акций «первые месяцы дешевле». - 🏷️ Кастомные поля и теги — позволяют маркировать аккаунты участниками программы, сегментировать клиентов и управлять логикой на стороне интеграции.
- 🔌 Плагинная архитектура — точки расширения для инвойсов, платежей и уведомлений, через которые можно встроить произвольную бонусную логику.
Каждый из этих инструментов решает свою задачу, и комбинация нескольких обычно закрывает большинство маркетинговых сценариев без доработки ядра.
Kill Bill не имеет встроенного модуля лояльности, но кредиты, скидочные фазы каталога и плагины покрывают типовые бонусные механики.
Кэшбэк через кредиты на счёте
Самый прямолинейный способ начислить «бонусы» — создать кредит на аккаунте клиента через API. Кредит в Kill Bill — это сумма в валюте аккаунта, которая уменьшит сумму следующего инвойса. Начисление выполняется запросом к эндпоинту кредитов, например через POST /1.0/kb/credits с указанием аккаунта и суммы.
Логика начисления при этом живёт вне Kill Bill: ваш сервис отслеживает события (успешная оплата, достижение порога трат, годовщина подписки) и вызывает API биллинга. Удобный источник событий — push-уведомления Kill Bill или плагин нотификаций, которые срабатывают на создание инвойса и платёжные транзакции.
⚠️ Внимание: кредит в Kill Bill — это денежная сумма, а не абстрактные «баллы». Если маркетингу нужны именно баллы с собственным курсом конвертации, сгоранием по сроку и лимитами на списание, храните баланс баллов во внешней системе, а в Kill Bill транслируйте только итоговое списание в виде кредита или скидки.
Чтобы кэшбэк не начислялся на возвраты и чарджбэки, слушайте не только событие успешного платежа, но и события возвратов — и делайте корректирующее списание.
Скидки за стаж и персональные тарифы через каталог
Каталог Kill Bill — это XML-описание продуктов, планов и фаз ценообразования. Фаза типа discount позволяет задать сниженную цену на ограниченный период, после чего подписка автоматически переходит на постоянную фазу evergreen. Это штатный механизм для акций вроде «скидка на первые три месяца».
Для персональных предложений участникам программы лояльности обычно используют один из двух подходов:
- 📦 Отдельные планы в каталоге для «золотых» и «серебряных» участников — клиент переводится на нужный план операцией смены плана.
- 📦 Версионирование каталога — новые версии каталога с особыми ценами, при этом существующие подписки сохраняют свои условия.
Второй подход аккуратнее: смена плана может триггерить перерасчёты и прорацию, что не всегда желательно в середине биллингового цикла. Поведение при смене плана зависит от настроек выравнивания (billing alignment) и политик, заданных в каталоге, поэтому перед внедрением стоит проверить сценарий на тестовом окружении с вашей версией каталога.
Собственный плагин: когда штатных средств мало
Когда требования выходят за рамки «начислить кредит по событию» — например, нужно автоматически уменьшать сумму каждого инвойса на процент, зависящий от уровня клиента, — на помощь приходит invoice plugin API. Плагин инвойсов перехватывает генерацию инвойса и может добавлять или изменять его позиции до финализации.
Типовая архитектура такого решения выглядит так:
☑️ Шаги реализации скидки через плагин инвойсов
Плагин пишется на Java и разворачивается вместе с Kill Bill — через OSGi-контейнер или как отдельный сервис, в зависимости от выбранной схемы деплоя. Точную структуру интерфейсов и способ установки для вашей версии платформы стоит сверять с официальной документацией Kill Bill: API плагинов эволюционирует между релизами.
⚠️ Внимание: плагин инвойсов выполняется синхронно при генерации инвойса. Обращение из него к медленной внешней CRM по сети может задержать весь биллинговый цикл. Кэшируйте данные об уровнях лояльности локально или обновляйте их асинхронно заранее.
Сравнение подходов к реализации лояльности
Выбор механизма зависит от сложности бонусной логики и требований к отчётности. Сводная картина по основным вариантам:
| Подход | Сложность внедрения | Гибкость | Типовой сценарий |
|---|---|---|---|
| Кредиты на аккаунте | Низкая | Средняя | Кэшбэк за оплату, компенсации |
| Скидочные фазы каталога | Низкая | Низкая | Акции для новых клиентов |
| Внешняя система баллов + API | Средняя | Высокая | Баллы с курсом и сгоранием |
| Плагин инвойсов | Высокая | Максимальная | Автоскидка по уровню клиента |
На практике команды часто комбинируют подходы: баллы и уровни живут в CRM, скидка применяется плагином инвойсов, а разовые поощрения начисляются кредитами. Такая связка не требует модификации ядра Kill Bill и переживает обновления платформы с минимальными правками.
Почему не стоит хранить баллы в кастомных полях аккаунта
Кастомные поля в Kill Bill предназначены для метаданных, а не для транзакционных данных. У них нет истории изменений, нет защиты от гонок при параллельном списании и нет механизма сверки. Баланс баллов — это по сути финансовый показатель, и ему нужна система с транзакциями, журналом операций и возможностью аудита.
Интеграция с внешними системами лояльности
Если в компании уже работает маркетинговая платформа или CRM с модулем лояльности, Kill Bill обычно занимает роль исполнителя: внешняя система принимает решения, биллинг их применяет. Связка строится на двух каналах.
Первый канал — события из Kill Bill наружу. Push-уведомления и плагины нотификаций отдают события о платежах, инвойсах и изменениях подписок; внешний сервис на их основе пересчитывает баллы и уровни. Второй канал — вызовы API Kill Bill извне: начисление кредитов, добавление тегов, смена плана. Обе операции выполняются через REST API с аутентификацией и указанием tenant в заголовках.
Здесь важно продумать идемпотентность: при повторной доставке события или ретрае запроса бонус не должен начислиться дважды. Практичный приём — использовать уникальный идентификатор события или платежа как ключ дедупликации на стороне вашего сервиса лояльности.
Храните в Kill Bill ссылку на ID клиента во внешней системе лояльности через кастомное поле аккаунта — это упростит сверку и расследование расхождений.
Типичные ошибки и ограничения
Первая частая ошибка — попытка эмулировать баллы отрицательными позициями инвойса вручную. Такие правки ломают отчётность и усложняют возвраты: для скидок корректнее использовать кредиты или плагин инвойсов, которые штатно участвуют в расчётах.
Вторая — начисление бонусов до фактической оплаты. Событие создания инвойса не означает поступления денег: ориентируйтесь на успешную платёжную транзакцию, иначе получите начисления по неоплаченным счетам. Третья ошибка — игнорирование мультивалютности: если аккаунты работают в разных валютах, курс конвертации баллов нужно фиксировать на момент операции и хранить во внешней системе.
Наконец, помните об ограничении масштаба: каталог с сотнями персональных планов становится неподдерживаемым. Если уровней лояльности много, лучше оставить в каталоге базовые планы, а дельту цены реализовывать плагином или кредитами.
Решения о бонусах принимайте во внешней системе, а Kill Bill используйте как надёжный исполнитель: кредиты, теги, планы и плагин инвойсов.
Частые вопросы
Есть ли в Kill Bill встроенный модуль программы лояльности?
Нет, отдельного модуля бонусов или баллов в платформе нет. Лояльность собирается из штатных механизмов — кредитов на счёте, скидочных фаз каталога, тегов и плагинов — либо выносится во внешнюю систему, интегрированную через API.
Чем кредит на аккаунте отличается от скидки в каталоге?
Кредит — это денежная сумма на счёте конкретного клиента, которая зачитывается в следующий инвойс; его можно начислить в любой момент через API. Скидочная фаза каталога — это правило ценообразования в плане, которое действует на всех подписчиков этого плана в течение заданного периода.
Можно ли автоматически применять персональную скидку к каждому инвойсу?
Да, для этого служит плагин invoice plugin API: он перехватывает генерацию инвойса и добавляет корректирующую позицию по вашей логике. Данные об уровне клиента плагин может брать из тегов аккаунта или из локального кэша, синхронизируемого с CRM.
Как не начислить бонусы дважды при повторной доставке события?
Используйте идемпотентную обработку: сохраняйте уникальный идентификатор платежа или события и проверяйте его перед начислением. Повторное событие с уже обработанным идентификатором должно игнорироваться.
Где хранить баланс бонусных баллов, если нужны баллы, а не деньги?
Во внешней системе с транзакционным журналом — CRM или специализированном сервисе лояльности. Кастомные поля Kill Bill для этого не подходят: у них нет истории операций и защиты от параллельных изменений. В Kill Bill передавайте только итоговый результат — кредит или скидку.