# Глобальные loyalty-платформы: устройство, API, embedded-модель, партнёрская модель и ценообразование (API-first/headless и embedded loyalty; состояние на сентябрь 2026)

*Методика: приоритет — официальная документация и страницы вендоров (проверены 24–25.09.2026). Вторичные источники (обзоры, блоги конкурентов) и факты, взятые только из сниппетов поисковой выдачи, помечены явно. Бюджет веб-поиска сессии был исчерпан в ходе работы, поэтому часть вопросов (Clover, Gartner) осталась в Gaps.*

## 1. Open Loyalty: история (open-source PHP/Symfony, CQRS/event sourcing → SaaS/API-first), доменная модель, API, уроки из кода и документации, причины смены модели

### Takeaway
Open Loyalty родился в 2017 году как open-source (MIT) продукт software house Divante на Symfony + Broadway (CQRS/event sourcing) + Doctrine/PostgreSQL + Elasticsearch; open source служил «доказательством реальности» продукта, а деньги приносили Enterprise-лицензии; попытка SMB-SaaS в 2019 провалилась («продукт слишком сложен для SaaS-клиентов»). Сегодня это закрытый headless/API-first enterprise SaaS: мультиарендность (tenant = `storeCode` в URL), несколько кошельков (wallet types) с pending/expiration, кампании «триггер → условия → эффекты», challenges/tiers/badges/leaderboards, вебхуки с HMAC, MCP-сервер для AI-агентов и цена за «активных участников».

### Cited Findings
**История и бизнес-модель**
- Основатель Karl Bzik создал Open Loyalty внутри software house Divante; официальный запуск на GitHub — 7 марта 2017 г. — [Karl Bzik, «10 lessons from founding Open Loyalty», 30.12.2019](https://www.linkedin.com/pulse/10-lessons-from-founding-open-loyalty-karl-bzik)
- Open source выбран как инструмент доверия: публикация Open Source Edition «helped prove to the clients that our product is real and reliable», что было критично, пока не было кейсов — [Karl Bzik, LinkedIn](https://www.linkedin.com/pulse/10-lessons-from-founding-open-loyalty-karl-bzik)
- Основная монетизация — лицензии Enterprise Edition для омниканальных ритейлеров; целевые покупатели — CTO и технически подкованные маркетологи — [Karl Bzik, LinkedIn](https://www.linkedin.com/pulse/10-lessons-from-founding-open-loyalty-karl-bzik)
- Попытка пивота в SaaS длилась ~3 месяца и не удалась: «our current product is too complicated for most SaaS clients»; фокус вернули на enterprise-лицензирование; вывод автора: «The business model needs to be in line with the stage of the company and the evolution of the product» — [Karl Bzik, LinkedIn](https://www.linkedin.com/pulse/10-lessons-from-founding-open-loyalty-karl-bzik)
- Команда выросла с 2 до 15 человек в 2017–2018 гг. (автор называет это ошибкой) и сократилась до 10 к концу 2019 г. — [Karl Bzik, LinkedIn](https://www.linkedin.com/pulse/10-lessons-from-founding-open-loyalty-karl-bzik)
- Divante — материнская компания, но Open Loyalty работает отдельно и относится к Divante как к одному из партнёров (по сниппету поиска) — [Open Loyalty News](https://www.openloyalty.io/news/divante-partnered-with-open-loyalty-and-created-a-successful-source-of-new-projects)
- Обзорщики в 2026 г. подчёркивают: несмотря на название, Open Loyalty — управляемый SaaS (также упоминается on-premise), а не open source; open-source репозиторий называют заброшенным (вторичные источники, по сниппетам) — [WiserReview](https://wiserreview.com/blog/open-loyalty-alternatives/); [Joy](https://joy.so/blog/loyalty-platform-open-source/)
- Пакет `divante-ltd/open-loyalty-framework` на Packagist: «This package is abandoned and no longer maintained. No replacement package was suggested»; 4 154 установки, 27 звёзд; репозиторий github.com/DivanteLtd/open-loyalty-framework — [Packagist](https://packagist.org/packages/divante-ltd/open-loyalty-framework)
- URL исходного репозитория github.com/OpenLoyalty/openloyalty при проверке 25.09.2026 вернул HTTP 404 — [GitHub](https://github.com/OpenLoyalty/openloyalty)
- Сохранившийся форк описан как «Fork from Divante Openloyalty - MIT License Version»; в README упомянуты три редакции, причём open-source редакция ограничена 1000 участников и предназначена «for testing purposes only» — [GitHub ad3n/Openloyalty](https://github.com/ad3n/Openloyalty)

**Архитектура open-source версии (что видно в коде и старой документации)**
- «Open Loyalty is based on Symfony»; Doctrine — ORM и слой абстракции БД (DQL); «Broadway is a project providing infrastructure and testing helpers for creating CQRS and event sourced applications» — [OL legacy docs: Architecture overview](https://docs.openloyalty.io/en/latest/developer/architecture/overview.html)
- Код разделён на Bundles (интеграция бизнес-логики с Symfony) и Components («It's a heart of our software. Here lies are business rules of the loyalty program», построены по DDD) — [OL legacy docs](https://docs.openloyalty.io/en/latest/developer/architecture/overview.html)
- Три фронтенда поверх REST API: Admin Cockpit (администратор программы), Client Cockpit (портал участника: профиль, баллы, история, награды), POS Cockpit (регистрация клиентов и операции с баллами в точке продаж) — [OL legacy docs](https://docs.openloyalty.io/en/latest/developer/architecture/overview.html)
- Структура репозитория: `backend/`, `frontend/`, `docker/`, `kubernetes/`; стек Symfony, Broadway, Elasticsearch, PostgreSQL, Docker; доменные компоненты Account, Customer, Level, Campaign, Transaction, Segment, EarningRule, Pos, Seller, Email, Import — [GitHub ad3n/Openloyalty](https://github.com/ad3n/Openloyalty)
- JWT-аутентификация (Lexik JWT) с отдельными логинами admin / customer / seller и refresh-токенами; системные события (регистрация, обновление, деактивация клиента, сегменты) и доменные события (покупка награды-кампании) — [Packagist](https://packagist.org/packages/divante-ltd/open-loyalty-framework)
- Группы REST API legacy-версии: Customer API, Customer Campaign API, Customer Level API, Customer Earning API, Customer Points transfers, Level API, Earning Rule, Reward Campaigns API, Campaigns categories API, Segment API, Transactions, Points transfers, POS API, Seller API, Store API, Admin Users API, Analytics API, Audit API, Event API, Webhooks, Settings API, ACL API — [OL legacy REST API index](https://docs.openloyalty.io/en/latest/api/index.html)

**Современная SaaS-версия: доменная модель**
- Позиционирование: «business logic — earning rules, tiers, campaigns, member profiles, rewards — lives in the engine and is controlled entirely via REST API»; слой представления полностью отделён от движка — [openloyalty.io: Loyalty Program API](https://www.openloyalty.io/technology/loyalty-program-api)
- Wallets: «Wallet types define how balances work in your loyalty program»; default wallet нельзя деактивировать; настраиваемое имя единицы (Star/Stars); unit expiration method (когда истекают), unit pending method (сколько единицы остаются заблокированными); global units limitation и member units limitation (применяются и к автоматическим transfer’ам от кампаний); опционально отрицательный баланс — [OL: Wallet types and configuration](https://help.openloyalty.io/members-and-activity/wallets/wallet-types-and-configuration)
- Движения баланса оформлены как «unit transfers» (список, создание, импорт, управление) — [OL docs index (llms.txt)](https://help.openloyalty.io/llms.txt)
- Кампании: 6 типов триггеров — Purchase Transaction, Return Transaction (возврат, связанный с исходной покупкой), Internal Event (смена тира, активация участника, обновление профиля, прогресс достижения), Custom Event (внешнее событие по заранее заданной схеме), Achievement, Redemption Code; при событии система «evaluates all active campaigns with the same trigger» — [OL: Trigger types](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/trigger-types.md)
- В модели кампаний также: referral-кампании, campaign simulation, campaign limitation, expressions, custom attributes, follow-up и automation-кампании, фильтры позиций транзакции, «percent value distribution», индивидуальные настройки expiration/pending на уровне кампании — [OL docs index (llms.txt)](https://help.openloyalty.io/llms.txt)
- Custom events отправляются только через API (`POST /api/{storeCode}/customEvent`) после создания схемы события; достижения можно строить на подсчёте custom events (по сниппету поиска) — [OL: Custom Events](https://help.openloyalty.io/main-features/members/custom-events)
- Транзакции без участника получают статус «Not matched»; матчинг — автоматически (если payload/файл содержит валидные идентификаторы участника) или вручную по email, телефону, номеру карты; после матчинга начисляются единицы — [OL: Matching transactions](https://help.openloyalty.io/members-and-activity/transactions/matching-transactions.md)
- Геймификация и награды: tiers (configuration, benefits, metrics, analytics), leaderboards (rewarding cycle), badges, fortune wheels; rewards (типы, units conversion coupon, reward flow, fulfilment, массовая смена статуса, отмена погашенной награды, категории) — [OL docs index (llms.txt)](https://help.openloyalty.io/llms.txt)

**API, аутентификация, лимиты**
- Мультиарендный REST: `POST /api/{storeCode}/member`; «Store is referred to as Tenant in the admin panel», «Customer is referred to as Member in the admin panel» — [OL: Terms reference](https://help.openloyalty.io/technical-guide/terms-reference)
- Аутентификация: admin token, member token, access token / API key (постоянный токен в заголовке `X-AUTH-TOKEN`, генерируется для admin-пользователя, опционально с датой истечения, показывается один раз); SSO для админки через Okta, Microsoft Entra ID, Auth0 — [OL: Access token / API key](https://help.openloyalty.io/technical-guide/authentication/access-token-api-key.md); [OL docs index](https://help.openloyalty.io/llms.txt)
- Лимиты: таймаут API 60 с; `/login` и `/login_check` — 40 RPM на клиента; `_page` > 500 → ошибка (рекомендуется scroll-механизм); до 5 одновременных импортов/экспортов; файлы XML/CSV до 100 МБ; строки ≤255 символов, выражения ≤500; номер карты уникален в пределах tenant’а и регистрозависим — [OL: Limits](https://help.openloyalty.io/technical-guide/api-fundamentals/limits)
- Способы интеграции: REST API, webhooks, AWS S3 exports для пакетной выгрузки в DWH/BI; Postman-коллекции; заявлено «120 ms avg API response time», «99.99% guaranteed uptime», «1B loyalty events/month», AWS и «full instance data separation» — [openloyalty.io: Loyalty Program API](https://www.openloyalty.io/technology/loyalty-program-api)

**Multi-tenancy**
- Tenant создаётся с полями Currency (выбирается из списка, после создания не редактируется), Code, Name; часовой пояс — tenant timezone (по умолчанию) или «local time» события без конвертации; «Each tenant has its own database with a Members List, Translations, and so on»; глобальными (над tenant’ами) остаются Configuration, Administrators, Roles, Transactions, Tenants, My Profile — [OL: Tenants](https://help.openloyalty.io/administration/settings/tenants.md)
- Маркетинг: «unlimited number of different business tenants»; разные валюты, таймзоны и сегменты; отдельные схемы по странам; коалиционные программы нескольких брендов — [openloyalty.io: Multitenancy](https://www.openloyalty.io/product/multitenancy)
- Config duplication между tenant’ами (только в пределах одного environment): wallets, custom event schemas, rewards, segments, achievements, campaigns, referral campaigns, automations; зависимые сущности (tiers, segments, channels, collections) нужно заранее создать в целевом tenant’е; «the wallet code is not editable and must be unique» — [OL: Config duplication](https://help.openloyalty.io/global-management/config-duplication.md)

**Вебхуки**
- Каталог событий: TransactionRegistered, AvailablePointsAmountChanged, TransactionAssignedToCustomer, CampaignEffectWasApplied, PointsWillExpire, WalletBalanceUpdated, RewardRedemptionStatusChanged, CustomerBoughtReward, CouponWillExpire, CustomerRegistered, CustomerWasRegisteredWithoutActivation, CustomerUpdated, CustomerRequestedSendActivationCode, CustomerRequestedPasswordReset, CustomerPhoneNumberWasChanged, CustomerLevelChanged, LevelWillExpire, CustomerEmailWasChanged, CustomerDeactivated — [OL: What triggers a webhook](https://help.openloyalty.io/integrations-and-data-exchange/webhooks/what-triggers-a-webhook.md)

**Релизы 2026 и AI**
- Январь 2026 — импорт внешних кодов кампаний; февраль — «Achievements» переименованы в «Challenges» в UI и API, ручная правка прогресса; март — HMAC-подписи вебхуков, автогенерация номеров карт, badges как эффект кампаний; май — вебхук WalletBalanceUpdated на каждое изменение баланса; июнь — триггер «points activation» (pending → active), «Return transactions can now automatically cancel the associated unit transfers», подгруппы лидербордов; июль — tier analytics (потоки upgrade/downgrade), custom attributes на transfer’ах кампаний; август — Custom Fields («typed, validated fields» для Members, Campaigns, Rewards), Product Catalog (SKU, категории, бренды, атрибуты), назначение тира эффектом кампании, массовая смена статусов наград через CSV — [OL: What's new 2026](https://help.openloyalty.io/whats-new/2026.md)
- MCP-сервер `@open-loyalty/mcp-server` «exposes the Open Loyalty API as a set of MCP tools»: 145 tools в 22 доменах (участники, баллы, награды, кампании, сегменты, аналитика, аудит, custom events, webhooks); только локально по stdio (Node.js 18+); настройка через `OPENLOYALTY_API_URL`, `OPENLOYALTY_API_TOKEN`, `OPENLOYALTY_DEFAULT_STORE_CODE`; «treat the API token with the same care as an admin password»; документация соответствует v1.20.0 — [OL: MCP server](https://help.openloyalty.io/technical-guide/integration/mcp-server.md)

**Цены**
- Цена зависит от числа monthly Active Members: «An Active Member is a Registered Member who performs at least one Loyalty Event per calendar month»; структура — Platform Fee + Allowance Fee; «full API access and Admin UI, no feature limits»; SLA 99,99%, P1 < 30 мин, мониторинг 24/7; хранение данных в Европе, APAC и Северной Америке; ISO/IEC 27001, GDPR/CCPA; цифры не публикуются — [openloyalty.io/pricing](https://www.openloyalty.io/pricing)

### Inferences
- Траектория Open Loyalty — типичная для open-core B2B: OSS дал доверие и лиды, но при сложном enterprise-продукте плохо конвертировался; SMB-SaaS требовал радикально более простого продукта, поэтому пивот 2019 г. провалился. Для новой платформы: если нужен SMB-SaaS (standalone), «простота из коробки» (шаблоны программ, готовые виджеты, 15-минутный запуск) важнее гибкости движка; гибкость отдаётся через API и «advanced»-режим.
- Event sourcing (Broadway) естественно ложится на ledger баллов (иммутабельные transfer’ы, pending/expire, аудит, пересчёт тиров по истории), но полный CQRS/ES-стек (Symfony + Broadway + Elasticsearch-проекции + PostgreSQL) дорог в эксплуатации и сложен для контрибьюторов. Практичный компромисс для новой платформы — append-only ledger движений баллов + transactional outbox для доменных событий/вебхуков, без event sourcing всех агрегатов.
- Наследие event-модели видно в API даже сейчас: сущность «unit transfer», вебхуки в прошедшем времени (`CampaignEffectWasApplied`, `TransactionAssignedToCustomer`) — хороший образец именования каталога событий.
- Модель «tenant = `storeCode` в пути URL + глобальные админы/роли + config duplication» — готовый образец для «одна инсталляция → много мерчантов», но в OL роли/админы глобальны над tenant’ами; для ISV-сценария (партнёр управляет своими мерчантами) нужна дополнительная иерархия Partner → Merchant с изоляцией администраторов и ключей.
- Релизы 2026 показывают, чего рынок ждёт от «ядра» API-first движка: типизированные расширяемые поля, каталог товаров для правил, корректные возвраты (авто-отмена начислений), активация pending-баллов как триггер, подписанные вебхуки, событие на каждое изменение баланса.
- MCP-сервер поверх публичного API — дешёвый способ получить «AI-ready» позиционирование; стоит сразу проектировать API так, чтобы его можно было безопасно отдать агенту (узкие скоупы токенов, аудит, dry-run/симуляция).

### Gaps
- Не найдено первичного источника о дате закрытия/удаления исходного open-source репозитория и о смене лицензии (MIT → ограничение 1000 участников); GitHub-URL возвращает 404.
- Неизвестно, использует ли современная SaaS-версия CQRS/event sourcing внутри — инженерных публикаций не найдено.
- Публичных цифр цены нет; формат payload, политика ретраев вебхуков и полный список эффектов кампаний не извлечены.

## 2. Talon.One, Voucherify, Antavo, Comarch, Capillary, Annex Cloud, Kangaroo, Smile.io, LoyaltyLion, Yotpo: доменная модель по публичным API, оценка корзины (preview vs commit, возвраты/отмены), идемпотентность, вебхуки, SDK, лимиты, sandbox, multi-application/brand/currency

### Takeaway
Рынок сошёлся на трёх шаблонах обработки корзины: (1) stateful «customer session» с состояниями open → closed → cancelled/partially_returned и dry-run (Talon.One); (2) stateless validate/qualification (без побочных эффектов) → redeem (коммит) → rollback (Voucherify); (3) событийная модель checkout → checkout_accept/reject → refund/partial_refund с pending-баллами и дедупликацией по `transaction_id` (Antavo). Общий «стандарт» enterprise-класса: неизменяемый ledger с pending/expiring «бакетами», несколько кошельков/валют баллов и тир-структур, custom events со схемами, idempotency-ключи, HMAC-подписанные вебхуки с ретраями, разделение sandbox/live и изоляция данных по application/project/tenant. SMB e-commerce-приложения (Smile.io, LoyaltyLion, Yotpo) проще: activities/rules → points transactions → rewards, выдаваемые как коды скидок платформы, с OAuth для партнёрских приложений.

### Cited Findings
**Talon.One**
- Две API-плоскости: Integration API (передаёт live-данные в rules engine и получает effects) и Management API (администрирование ресурсов Campaign Manager; позволяет программно делать то же, что UI) — [API Evangelist: Talon.One (сторонний профиль)](https://github.com/api-evangelist/talon-one); [Talon.One glossary](https://www.talon.one/glossary/application-programming-interface)
- Customer session: open («can be modified as many times as needed»), closed («cannot be modified anymore, unless it is reopened programmatically»; купоны погашаются), cancelled (сессия исключается из аналитики, бюджеты откатываются), partially returned (эффекты по возвращённым позициям откатываются выборочно); переходы Open→Closed, Closed→Open (reopen), Open/Closed→Cancelled, Closed→Partially Returned — [Talon.One: Customer sessions](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions)
- «Loyalty points are updated when the session is closed or cancelled. Coupons, referral codes and awarded giveaway items are redeemed when the session is closed»; при отмене откатывается влияние на бюджеты «except for coupon creations», а «Attribute value updates are not rolled back»; лимиты бюджета проверяются на каждом обновлении, но расходуются только при закрытии; архивные кампании не участвуют в оценке правил — [Talon.One: Customer sessions](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions)
- Эндпоинты Integration API: `PUT /v2/customer_sessions/{id}` (UpdateCustomerSessionV2), `PUT .../reopen`, `POST .../returns` (ReturnCartItems); `PUT /v2/customer_profiles/{integrationId}` и bulk `PUT /v2/customer_profiles`; `POST /v2/events` и `POST /v3/events`; loyalty-ledger: `/v1/loyalty_programs/{id}/profile/{integrationId}/balances|points|transactions`, `/cards/{cardId}/balances|points|transactions`, `activate_points`, `join`, генерация карт, link/unlink карты к профилю, `delete_transactions`; coupon reservations; referrals (в т.ч. для нескольких адвокатов); audiences v2; `PUT /v1/catalogs/{catalogId}/sync`; rewards catalog/unlock; achievements; best prior price; `DELETE /v1/customer_data/{integrationId}` — [TalonOne.cs IntegrationApi.md](https://raw.githubusercontent.com/talon-one/TalonOne.cs/master/docs/IntegrationApi.md)
- Dry run: `dry=true`, параметр `now` для симуляции будущего/прошлого; «No data about the request or its response is stored»; «Send the complete cart state on every dry run… Do not send deltas»; вызывать при значимых изменениях корзины, а не на каждое действие пользователя — [Talon.One: Integration API best practices](https://docs.talon.one/docs/dev/integration-api/best-practices)
- Idempotency: заголовок `Idempotency-Key` для части POST/PUT; ключ ≤255 символов, по умолчанию валиден 24 ч после первого использования; ответные заголовки `Idempotent-Replayed: true`, `X-Idempotency-Created-At`, `X-Idempotency-Expires-At`, `X-Idempotency-Fingerprint`; «Idempotency is not supported for dry requests» — [Talon.One: best practices](https://docs.talon.one/docs/dev/integration-api/best-practices)
- `responseContent` позволяет запросить в ответе дополнительные блоки (customerProfile, triggeredCampaigns, loyalty и др.) — [Talon.One: best practices](https://docs.talon.one/docs/dev/integration-api/best-practices)
- Клиентская надёжность: короткие таймауты, ограниченные ретраи с backoff и jitter, circuit breaker, fallback; после записи подождать до 1 с перед чтением; «Serialize updates per session and profile» — параллельные обновления одной сессии/профиля дают 409 и гонки; «Always close sessions at checkout» — перед переходом к оплате — [Talon.One: best practices](https://docs.talon.one/docs/dev/integration-api/best-practices)
- Applications: группировка кампаний «by country, time zone, currency, or even by the teams»; окружения sandbox и live; в Application — кампании, API-ключи, сессии, профили; профили изолированы по environment; loyalty programs, audiences, giveaway pools — в пределах environment; «You cannot share customer activity or campaigns across different Applications» — [Talon.One: Applications](https://docs.talon.one/docs/product/applications/overview)
- Loyalty programs: profile-based и card-based (карты можно передавать и использовать совместно); subledgers — несколько балансов в одной программе; activation delay и validity баллов; начисление при закрытии сессии; одна программа может использоваться в нескольких Applications — [Talon.One: Loyalty programs](https://docs.talon.one/docs/product/loyalty-programs/overview)
- Развёртывание: для каждого клиента тройное резервирование инстансов API/app-сервера, БД — два сервера в warm-standby (по сниппету поиска FAQ; при прямой загрузке страница вернула 404) — [Talon.One FAQ](https://docs.talon.one/docs/dev/getting-started/faq)
- SDK и инструменты: клиенты на Python, Go, PHP, .NET, JS (legacy); пакет `talon-one-sdk` на PyPI в версии 26.2; Postman-коллекции Integration и Management API — [talon_one.py](https://github.com/talon-one/talon_one.py); [talon_go](https://github.com/talon-one/talon_go/blob/master/docs/Application.md); [TalonOnePHPsdk](https://github.com/talon-one/TalonOnePHPsdk/blob/master/README.md); [TalonOne.cs](https://github.com/talon-one/TalonOne.cs/blob/master/docs/IntegrationApi.md); [talon_one.js (legacy)](https://github.com/talon-one/talon_one.js/); [PyPI](https://pypi.org/project/talon-one-sdk/26.2/); [Postman](https://www.postman.com/talonone-rnd/talon-one/collection/3zq30db/-integration-api)

**Voucherify**
- Модель: Project (изолированное окружение с уникальными API-ключами; customers, products, campaigns и ID раздельны); 5 типов кампаний — discount coupons, loyalty cards, gift vouchers, referral codes, promotions (без кода; promotion tiers применяются автоматически); vouchers; customers и segments (static/dynamic); orders; products/SKU/collections; validation rules как переиспользуемые объекты; qualification («validates which incentives can be used in the customer's order»); validation vs redemption (до 30 redeemables за вызов); stacking; rollback («reverts a redemption»); distributions; metadata; custom events; webhooks — [Voucherify: Key concepts](https://docs.voucherify.io/get-started/key-concepts)
- Loyalty v2: program (`lprg_`) — контейнер для кошельков, правил, наград и участников; «up to 10 wallets, 100 rewards, 100 earning rules, one tier structure (up to 100 levels), and 100,000 members per program»; card definition (`lcdef_`) задаёт поведение баллов кошелька; member (`lmbr_`) — зачисление customer (`cust_`) в программу («Do not interchange `cust_…` and `lmbr_…`»); loyalty card (`lcrd_`) — баланс одного кошелька участника (код генерируется асинхронно); earning rules (`lern_`: триггеры orders, custom events, вход в сегмент), benefits (`lben_`), rewards (`lrew_`), tier structures (`lts_`/`lt_`); заказ `status: PAID` запускает начисление и нужен для pay-with-points; legacy `/v1/loyalties` «remains in maintenance mode»; после ACTIVE нельзя добавлять/менять кошельки и тир-структуры; в v2 нет нативного перевода баллов — [Voucherify: Loyalty v2 overview](https://docs.voucherify.io/guides/loyalty-v2-overview.md)
- Pending и expiring points как «buckets»: list / activate / cancel pending point bucket, list expiring points buckets, expire point bucket, card transactions — [Voucherify docs index (llms.txt)](https://docs.voucherify.io/llms.txt)
- Rollback redemption возможен до 3 месяцев назад; rollback stacked redemption откатывает все дочерние погашения по ID родительского (по сниппетам поиска) — [Voucherify: Rollback redemption](https://docs.voucherify.io/api-reference/redemptions/rollback-redemption); [Voucherify: Rollback stackable redemptions](https://docs.voucherify.io/reference/rollback-stacked-redemptions)
- Вендор описывает validation как dry run («reversible and free»), а redemption как commit с финансовыми последствиями; погашение пишется в audit-safe лог, повторные вызовы его не дублируют (маркетинговый глоссарий, по сниппету) — [Voucherify glossary](https://www.voucherify.io/glossary/incentive-redemption)
- Аутентификация: server-side `X-App-Id`/`X-App-Token`; client-side `X-Client-Application-Id`/`X-Client-Token` — только для эндпоинтов с пометкой «(client-side)» и при whitelisting домена/origin приложения в настройках проекта; OAuth-токены со `scope`, срок жизни 15 минут; по умолчанию две пары ключей на проект; при генерации ключа выбирается роль — [Voucherify: Authentication](https://docs.voucherify.io/guides/authentication.md)
- Лимиты (документация): Business — 100 req/min и 100 000 запросов за цикл; Organization — 2 000 req/min и 300 000; client-side — 5 запросов за 5 с с одного IP; вебхуки — 144 000 / 288 000 в сутки (отдельная очередь); sandbox-проекты — 100 вызовов в час; превышение «will block your access to the API immediately» — [Voucherify: Limits](https://docs.voucherify.io/guides/limits); противоречит странице цен (Business 100/мин и 25 000/мес; Organization 200/мин и 50 000/мес) — [Voucherify pricing](https://www.voucherify.io/pricing)
- Вебхуки (версия v2024-01-01): подпись в `x-voucherify-signature` (HMAC SHA-256 с секретом из Project Settings); 12 повторов с экспоненциальными интервалами (1, 2, 4, 8, 16, 32 мин … 17 ч 4 мин, финальный — через 24 ч); project-level и distribution-вебхуки; поля `id`, `project_id`, `created_at`, `type`, `data`, `source` — [Voucherify: Webhooks](https://docs.voucherify.io/reference/introduction-to-webhooks)
- Ошибки: JSON `{code, message, details, key}`; 400/401/404/429; ключи вида `quantity_exceeded`, `voucher_expired`, `voucher_not_active`, `customer_rules_violated`, `duplicate_found`, `invalid_payload`, `missing_order`, `non_active_program`, `zero_card_balance`; сообщения об ошибках можно кастомизировать в Project Settings — [Voucherify: Errors](https://docs.voucherify.io/api-reference/errors.md)
- Версионирование: `v1` в URL + датированная версия через `X-Voucherify-API-Version` (текущая v2018-08-01); по умолчанию используется версия из Project settings; «When we make backwards-incompatible changes to the API, we release new, dated versions» — [Voucherify: Versioning](https://docs.voucherify.io/api-reference/versioning.md)
- Bulk/async: массовые обновления vouchers/customers/products, batch create program members, async actions (list/get), экспорты (create/download), импорты (legacy codes, products CSV, orders) — [Voucherify docs index](https://docs.voucherify.io/llms.txt)
- Multi-brand: отдельные проекты для локаций, валют, брендов или стадий разработки либо один проект с категориями, labels, префиксами кодов и custom fields; проект изолирует валюту и таймзону, пользователей и доступы, metadata schema, API-ключи и вебхуки — [Voucherify: Brand management](https://docs.voucherify.io/docs/brand-management)
- SDK сгенерированы из OpenAPI (репозитории `sdk-java-openapi-based`, `sdk-php-openapi-based`); интерактивная документация позволяет вызывать API против своего sandbox-проекта (по сниппету) — [GitHub: sdk-java-openapi-based](https://github.com/voucherifyio/sdk-java-openapi-based); [GitHub: sdk-php-openapi-based](https://github.com/voucherifyio/sdk-php-openapi-based/blob/main/docs/Api/CampaignsApi.md); [Voucherify LinkedIn](https://www.linkedin.com/posts/voucherifyio_new-interactive-api-documentation-activity-7077665444735705088-pccm)

**Antavo**
- Набор API: Events API (все взаимодействия из e-commerce, POS, сайтов, приложений), Async Events API, Display API («the main headless API for building the customer loyalty experience»), Points Preview API (сколько баллов за товар, бонусы), Bulk Operations API, Coupons, Coupon Pools, Customer API, Entities API (rewards, challenges, stores, products), FAQ, Leaderboard, Offers, Rewards (legacy) — [Antavo APIs](https://developers.antavo.com/docs/antavo-apis)
- Аутентификация: подписанные запросы (API key + secret); bearer-токены для Async Events; rate limits: shared stack 1 500 req/min, dedicated stack 20 000 req/min на API-ключ (Async Events API не входит); языки через `Accept-Language` (ISO 639-1) — [Antavo APIs](https://developers.antavo.com/docs/antavo-apis)
- Покупка как набор событий: `checkout` (+ `checkout_item`), `checkout_update`/`checkout_update_item` (изменение pending-покупки до подтверждения, удаление позиций), `checkout_accept` (подтверждение), `checkout_reject`, `checkout_claim` (привязка гостевой транзакции к клиенту), `refund`, `partial_refund` («The customer's score is reduced, without altering the customer's number of spent points»), `refund_item`; повтор `transaction_id` отклоняется с `ERR_TX_ALREADY_EXISTS`; при refund «Burnt points will be restored as spendable points»; отклонённый checkout баллов не даёт — [Antavo: API events](https://developers.antavo.com/docs/api-events.md)
- Events API синхронный («each event is processed immediately when the request is received»), поддерживает bulk до 50 событий в запросе — [Antavo: About Events API](https://developers.antavo.com/reference/about-events-api)
- Async Events API: `POST /v1/async/events` → correlation ID; `GET /v1/async/events/{correlation_id}` для статуса и результата; «the system guarantees that events are processed in the order they were received», клиент должен дождаться 200 перед отправкой следующего события — [Antavo: Async Events API](https://developers.antavo.com/reference/about-async-events-api.md)
- Позиционирование: «AI Loyalty Cloud» для omnichannel, multi-brand, multi-country программ; API-first headless Loyalty Engine (сторонний профиль) — [API Evangelist: Antavo](https://github.com/api-evangelist/antavo)

**Comarch**
- «The Complete Loyalty Platform for Enterprise Growth»; масштаб «tens of millions of members»; AI: Customer Lifetime Value, Churn Prediction, Next Best Offer, Product Recommendations; развёртывание: «Comarch Cloud (SaaS)… hosted in Comarch's 16 secure global data centers», внешнее облако, on-premise, гибрид; «Open API and batch interfaces»; 9 вертикалей (аэропорты, автомобили, банки, топливный ритейл, grocery, страхование, ритейл, телеком, travel) — [Comarch Loyalty](https://www.comarch.com/trade-and-services/loyalty-marketing/)

**Capillary**
- Документация Loyalty+: Locations (business location, geographic grouping, business grouping, point of transaction — замена старой store hierarchy); Single и Multi Loyalty Programs, Coalition program, Subscription program; тиры (upgrade, renewal & downgrade); points и rolling expiry; Alternate Currencies; behavioral events (в т.ч. ingestion через dataflow); rewards catalog и типы наград; gift vouchers; Dataflow (бывш. Connect+) — no-code пайплайны данных; event notification / manage webhook; Neo Extension — фреймворк кастомных API-расширений; API V2 и V1.1; RBAC — [Capillary docs index (llms.txt)](https://docs.capillarytech.com/llms.txt); [Capillary docs](https://docs.capillarytech.com/); [Capillary: Loyalty+ overview](https://docs.capillarytech.com/docs/loyalty-overview.md)

**Annex Cloud**
- «Enterprise Loyalty Platform» на модульной SaaS-архитектуре: loyalty, gamification, social loyalty, surveys/quizzes/contests, reviews, referrals, receipt scanning, tiering, incentive engine; «125+ integrations»; «2B loyalty events a year», «500M transactions a year»; AI-набор Journey Catalyst (churn risk, spend lift, predictive reward matching); B2B и B2C, несколько брендов/регионов — [Annex Cloud](https://www.annexcloud.com/)

**Kangaroo Rewards**
- API: «Real-time, bidirectional data sync» профилей, баллов и тиров; «Sync purchases, returns, and spend from any POS or eCommerce platform instantly»; триггеры кампаний/workflow; масштаб «1→500+ locations» — [Kangaroo: API](https://loyalty.kangaroorewards.com/api/)
- Интеграции с Lightspeed Retail/Restaurant/eCom, Shopify POS и eCom, WooCommerce, Magento, Vend (по сниппету) — [Kangaroo: Integrations](https://loyalty.kangaroorewards.com/integrations/)

**Smile.io**
- REST-ресурсы: customers, points transactions (начисление/списание), activities (запись действия клиента), rewards, reward fulfillments (выданные награды), VIP tiers и VIP tier changes, referrals и referral settings; аутентификация API key или OAuth 2.0 (есть гайд миграции с ключей на OAuth), access scopes, webhook-топики для приложений; фронтенд — Smile.js (полностью кастомный UI) и Smile UI (готовая панель и launcher); отдельный гайд для headless/SPA — [Smile dev docs index (llms.txt)](https://dev.smile.io/llms.txt)
- Rate limit: «All API tokens are permitted to make up to 10 requests per second», при превышении — HTTP 429 — [Smile: Rate limits](https://dev.smile.io/api/rate-limits.md)

**LoyaltyLion**
- Headless API с датированной версией в пути (`/headless-api/2025-06/...`): get customer, initialize session, enroll customer, set birthday, get configuration; «complete rules» (clickthrough, подписки в соцсетях); погашение наград — cart/collection/product discount voucher, free shipping voucher, gift card; reward refund; REST v2 — customers, add points, transactions, webhooks; аутентификация API keys и OAuth (token & secret — deprecated); JS SDK с customer authentication — [LoyaltyLion docs index (llms.txt)](https://developers.loyaltylion.com/llms.txt)
- Вебхуки: поля `id`, `topic`, `created_at`, `payload`; подпись `x-loyaltylion-hmac-sha256` (base64 HMAC-SHA256 сырого тела); at-least-once («you may receive duplicate webhooks»), дедупликация по `id`; ответ 200 в течение 5 с; экспоненциальные ретраи; после 5 неудач — email, после 30 — подписка удаляется; подписки привязаны к OAuth-приложению — [LoyaltyLion: Webhooks overview](https://developers.loyaltylion.com/api-reference/v2/webhooks/overview.md)

**Yotpo Loyalty**
- API/headless — на всех планах; multi-store/multi-domain — на всех; «cross-market management is available on higher tiers and Enterprise» — [Yotpo Loyalty pricing](https://www.yotpo.com/pricing/loyalty/)
- Поддерживает Shopify, BigCommerce, Adobe Commerce, Salesforce Commerce Cloud, WooCommerce и headless через API; не-Shopify платформы интегрированы заметно слабее (вторичный источник) — [Rivo](https://www.rivo.io/blog/yotpo-loyalty-pricing)

**Отраслевой чек-лист (Talon.One, 31.07.2026)**
- «Idempotency is non-negotiable for point accrual, redemption, and reward issuance»; вебхуки — ретраи, подпись, логи доставки, безопасная обработка out-of-order, уникальные ID событий; раздельные лимиты на чтение, запись и async; URL-версионирование (пример `/api/v1.4/products/123`) с понятной политикой депрекации; произвольные key-value metadata на профилях и событиях; регистрация схем custom events; нетранзакционные события (опросы, отзывы); «Multiple tier tracks and named point currencies»; cart-native интеграция в checkout; golden record — в CDP, а не в POS/ERP; sandbox parity с продом; SOC 2 Type II, GDPR DPA, PCI DSS — [Talon.One: How to evaluate a loyalty API](https://www.talon.one/blog/evaluate-loyalty-api)

### Inferences
- Сводка шаблонов оценки корзины (по находкам выше):

| Платформа | Preview | Commit | Отмена/возврат | Дедупликация |
|---|---|---|---|---|
| Talon.One | `dry=true` на update session (полная корзина) | session `state: closed` | `cancelled`, `POST …/returns` → `partially_returned`, reopen | `Idempotency-Key` (24 ч), кроме dry |
| Voucherify | validate / qualification | redeem (orders `PAID` для loyalty v2) | rollback (≤3 мес., stacked — по parent ID) | заявлена вендором, механизм в извлечённых доках не описан |
| Antavo | Points Preview API; pending checkout | `checkout_accept` | `checkout_reject`, `refund`, `partial_refund`, `refund_item` | уникальный `transaction_id` |
| Square | CalculateLoyaltyPoints | AccumulateLoyaltyPoints; reward reserve → redeem | delete reward (возврат баллов), AdjustLoyaltyPoints | `idempotency_key` |
| Toast (POS→провайдер) | LOYALTY_INQUIRE | LOYALTY_REDEEM / LOYALTY_ACCRUE | LOYALTY_REVERSE | идемпотентная обработка SIGNUP обязательна; отдельный раздел «Network failure and idempotence» |

- Для новой платформы рационально поддержать одновременно: stateless `evaluate` (dry, полная корзина, без записи) → идемпотентный `commit` по внешнему ID заказа/чека → `reverse`/`return` по строкам и полной отмене; для оффлайн/POS-сценариев — событийный вход (`checkout`/`accept`/`refund`) с pending-баллами, чей срок активации согласован с окном возврата.
- Ledger: хранить баллы бакетами (pending / active / expiring) с FIFO-списанием по сроку, как Voucherify buckets и OL pending/expiration method; поддержать несколько кошельков/валют и subledgers (Talon.One) — это нужно для коалиций и мультибрендов; погашение награды — через резервирование баллов (Square), а не мгновенное списание.
- Типизированные префиксы ID (`lprg_`, `lmbr_`, `cust_`, `lcrd_`) и разделение «customer (профиль)» vs «member (участие в программе)» (Voucherify) снижают число интеграционных ошибок и естественно поддерживают несколько программ у одного мерчанта.
- Для высокой нагрузки нужен отдельный async-канал приёма событий с correlation ID и порядком обработки на клиента (Antavo), плюс bulk до десятков событий за запрос; синхронный путь — только для checkout.
- Клиентские (публичные) ключи с allowlist origin и ограниченным набором эндпоинтов (Voucherify) + короткоживущие токены участника (member token OL, customer authentication в SDK LoyaltyLion) — базовый набор для виджетов и мобильных приложений мерчантов.
- В SMB e-commerce доминирует модель «activity/rule → points transaction → reward fulfilment как код скидки платформы» (Smile, LoyaltyLion); API и SDK часто используются как рычаг апсейла (у Smile API только с Growth — см. раздел 6).

### Gaps
- Числовые rate limits Talon.One, его каталог вебхуков и схема подписи не извлечены (прямые страницы не найдены, веб-поиск исчерпан); фраза «5 000 messages per minute» встречалась только в статье стороннего интегратора (Cordial) и не подтверждена как лимит Talon.One.
- Voucherify: формальный механизм idempotency (заголовок/ключ) в извлечённых документах не найден — только маркетинговое утверждение.
- Antavo: исходящие вебхуки, модель sandbox/environments и multi-brand API в индексе документации не найдены.
- Comarch, Capillary, Annex Cloud: детали API (idempotency, лимиты, sandbox, возвраты) публично не извлечены; страница Capillary Core Concepts отдала только навигацию.
- Yotpo Loyalty API (ресурсы, вебхуки) и Kangaroo API (аутентификация, вебхуки) детально не исследованы.

## 3. Embedded loyalty в POS и commerce-платформах: Square Loyalty (и API для сторонних разработчиков), Toast Loyalty, Lightspeed Loyalty, Clover, Shopify; цена add-on и отображение в POS/checkout

### Takeaway
POS-вендоры продают лояльность как встроенный платный add-on за локацию или в составе старшего пакета (Square — ≈$45/мес за локацию или в Square Plus; Toast — ≈$50/мес за локацию или в маркетинговом бандле; Lightspeed — в пакете Core для Retail и во всех пакетах Restaurant; цифры по Square/Toast/Lightspeed — из вторичных источников) и показывают её прямо в checkout (номер телефона на экране покупателя, кнопка Rewards, автоматическое начисление). Для сторонних провайдеров есть два противоположных контракта: «провайдер вызывает API POS» (Square Loyalty API — программа read-only и одна на продавца, фича требует платной подписки продавца) и «POS вызывает провайдера» через единый HTTPS-endpoint с типами SEARCH/SIGNUP/INQUIRE/REDEEM/ACCRUE/REVERSE (Toast). Shopify разносит лояльность на Discount Functions (скидки), GraphQL-коды скидок и POS UI extensions (UI в кассе).

### Cited Findings
**Square**
- Loyalty API позволяет «integrate Square Loyalty into third-party applications, such as eCommerce websites, mobile applications, and POS solutions»; объекты: Loyalty Program, Accrual Rules (SPEND, VISIT, CATEGORY, ITEM_VARIATION), Reward Tiers, Loyalty Account, Loyalty Event («immutable ledger entries for all balance-changing transactions»), Loyalty Reward, Loyalty Promotions — [Square: Loyalty API overview](https://developer.squareup.com/docs/loyalty-api/overview)
- «A Square seller must have an active Square Loyalty subscription to use loyalty features»; при неактивной подписке запись возвращает `404 NOT_FOUND`; «Loyalty programs are read-only with the Loyalty API» (настраиваются только в Dashboard); «A Square seller can have only one loyalty program» — [Square: Loyalty API overview](https://developer.squareup.com/docs/loyalty-api/overview)
- CalculateLoyaltyPoints («Get the number of points a buyer would earn from a purchase») и AccumulateLoyaltyPoints; OAuth-разрешения `LOYALTY_READ`/`LOYALTY_WRITE`; вебхуки `loyalty.account.created/updated/deleted`, `loyalty.program.created/updated`, `loyalty.event.created` — [Square: Loyalty API overview](https://developer.squareup.com/docs/loyalty-api/overview)
- CreateLoyaltyReward «Removes the required points from the loyalty account balance and holds them in reserve until the reward is redeemed or deleted»; состояния ISSUED / REDEEMED / DELETED; при указании `order_id` Square применяет скидку к позициям заказа, а после оплаты заказа сам вызывает RedeemLoyaltyReward; без Orders API — явный RedeemLoyaltyReward; удаление возвращает зарезервированные баллы; погашенную награду удалить нельзя — корректировка через AdjustLoyaltyPoints — [Square: Loyalty rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards)
- Продукт: «Try Square Loyalty free for 30 days»; запись в программу на POS, на сайте Square, через инвойс; «Customers can type in their phone number and get points automatically when they check out»; интеграция с Square Marketing; сторонние приложения через App Marketplace — [Square Loyalty](https://squareup.com/us/en/software/loyalty)
- Лояльность («Create a custom rewards program that connects to your POS») входит в Square Plus — [Square pricing](https://squareup.com/us/en/pricing)
- Цена: $45/мес за локацию (3 локации = $135/мес); также упоминается Square Plus за $49/мес за локацию; утверждается отсутствие free trial — вторичные источники (блоги конкурентов), частично противоречат официальным «30 days free» — [Loop Fans](https://loop.fans/blog/square-loyalty-program-review); [Favecard](https://www.favecard.co/en/blog/square-loyalty-review/)

**Toast**
- Сторонний провайдер реализует один HTTPS REST endpoint: «The Toast platform sends requests to that single endpoint… for all loyalty program transactions»; тип транзакции — в заголовке `Toast-Transaction-Type`; в документации есть разделы о latency requirements, «Network failure and idempotence», аутентификации — [Toast: Loyalty integration overview](https://doc.toasttab.com/doc/devguide/apiLoyaltyIntegrationOverview.html)
- Типы транзакций: `LOYALTY_SEARCH` (сотрудник нажал Rewards без идентификации гостя; 200 со списком или 404), `LOYALTY_SIGNUP` (создание аккаунта с guest-facing display или киоска; провайдер обязан обрабатывать повторы идемпотентно), `LOYALTY_INQUIRE` (во время набора заказа, может вызываться многократно — доступные офферы и проверка применённых), `LOYALTY_REDEEM` (при оплате; провайдер может отклонить офферы), `LOYALTY_ACCRUE` (асинхронно после оплаты; в offline-режиме запросы копятся и отправляются позже), `LOYALTY_REVERSE` (void чека или позиций — откат REDEEM/ACCRUE по ID исходной транзакции) — [Toast: Transaction types](https://doc.toasttab.com/doc/devguide/apiLoyaltyTransactionDescriptions.html)
- После подключения на POS появляются кнопки Gift Card и Rewards; партнёр получает Restaurant GUID для маппинга в своей системе; сторонняя лояльность в Toast Online Ordering требует предварительной интеграции с Toast POS (по сниппетам) — [Toast support: Gift card & loyalty partners](https://support.toasttab.com/en/article/Using-a-Gift-Card-Partner-Integration); [Toast support: OO third-party loyalty](https://support.toasttab.com/en/article/Toast-Online-Ordering-Pro-Third-Party-Loyalty)
- Цена Toast Loyalty — вторичные источники расходятся: ~$50/мес за локацию как add-on (по одному источнику — плюс процент от продаж, связанных с лояльностью) либо только в составе бандла Marketing Essentials за $185/мес (вместе с подарочными картами, email и SMS) — [Loop Fans](https://loop.fans/blog/square-loyalty-vs-toast-loyalty-comparison); [UpMenu](https://www.upmenu.com/blog/toast-pricing/); [Favecard](https://www.favecard.co/en/blog/toast-loyalty-program/)

**Lightspeed**
- Лояльность встроена («Get a pos system with a loyalty program right out of the box»): запись «right at the point of sale», без физических карт, баллы и награды отслеживаются в POS; баллы на отдельные товары; «no limit to how many tiers»; email/SMS; апгрейд Lightspeed Advanced Marketing (сегментация, поведенческие автоматизации); омниканально (магазин + онлайн) — [Lightspeed Retail: Loyalty](https://www.lightspeedhq.com/pos/retail/loyalty/)
- Цена: в Retail лояльность требует пакета Core ($149/мес за одну кассу при годовой оплате или $179 помесячно), в Restaurant включена во все пакеты (вторичный источник) — [Merchant Maverick](https://www.merchantmaverick.com/what-is-lightspeed-loyalty/)

**Shopify**
- Discount Functions (Shopify Functions) для скидок, которых нет «из коробки»; три класса — product, order, shipping; приложения создают коды скидок через GraphQL (`discountCodeBasicCreate`, `discountCodeBxgyCreate` и др.) со scope `write_discounts`; для Discount Function доступен network access для валидации во внешних системах — [Shopify: Discounts](https://shopify.dev/docs/apps/build/discounts)
- POS UI extensions: Tile (плитка на главном экране POS), Action (пункты меню и модальные окна), Block (inline-контент на нативных экранах, включая чеки); примеры — «show customer loyalty points», отображение статуса лояльности клиента через аутентифицированные запросы к бэкенду приложения — [Shopify: POS UI extensions](https://shopify.dev/docs/api/pos-ui-extensions)
- Лояльность-приложения поддерживают Shopify POS: Smile — «Native support for Shopify POS» на всех планах; Yotpo — на всех планах; LoyaltyLion — одна локация на Classic, несколько — на Advanced/Plus — [Smile pricing](https://smile.io/pricing); [Yotpo Loyalty pricing](https://www.yotpo.com/pricing/loyalty/); [LoyaltyLion pricing](https://loyaltylion.com/pricing)

### Inferences
- Для «встраивания в собственные продукты» стоит спроектировать сразу два контракта: (а) provider API в стиле Square (calculate → accumulate/commit, reward reserve → redeem/delete, idempotency keys) — им пользуются кассы/e-com создателя платформы; (б) «loyalty provider SPI» в стиле Toast (SEARCH/SIGNUP/INQUIRE/REDEEM/ACCRUE/REVERSE через один endpoint) — чтобы наш движок можно было подключить к чужим POS и чтобы наши POS могли принимать сторонние программы. Эти операции 1:1 ложатся на evaluate/commit/reverse из раздела 2.
- Оффлайн-режим касс (Toast копит ACCRUE и шлёт позже) требует, чтобы API принимал запоздалые и неупорядоченные начисления с исходным временем операции и дедупликацией по ID транзакции POS.
- UX-паттерн embedded-лояльности: идентификация по телефону на экране покупателя, авто-запись в программу, кнопка Rewards, награда применяется как скидочная строка заказа и автоматически погашается при оплате (Square) — встроенный UI должен быть частью нашей кассы/чекаута, а не внешним виджетом.
- Ограничения Square (одна программа на продавца, конфигурация только в Dashboard, фича платная у продавца) — антипаттерн для ISV-платформы: партнёрам нужна программная настройка программы через API и шаблоны.
- Якорь цены для SMB-мерчантов POS — $45–50/мес за локацию или включение в старший пакет POS (Lightspeed, Square Plus); это задаёт потолок для embedded-add-on в собственных продуктах создателя.

### Gaps
- Clover: первичные данные не получены (прямой URL документации вернул 404, веб-поиск исчерпан) — неизвестно, есть ли у Clover нативная лояльность, её цена и API для сторонних провайдеров.
- Официальные цены Square Loyalty и Toast Loyalty не подтверждены первичными страницами (страница Toast вернула 403).
- Лимиты исполнения Shopify Functions и поддержка Discount Functions в POS не проверены.
- Аутентификация (JWT) и точные правила идемпотентности в Toast loyalty integration не извлечены.

## 4. Партнёрская и мультиарендная модель: provisioning и управление многими мерчантами через API, white-label UI, SSO, партнёрский биллинг и usage-отчётность

### Takeaway
Лучшие практики: явная иерархия «организация/партнёр → изолированный контейнер мерчанта (project / application / tenant) с sandbox/live»; провижининг контейнеров через отдельный Management API со своими ключами (Voucherify, Enterprise-фича; Talon.One Management API); доступ сторонних приложений через OAuth со скоупами и вебхуком отзыва (Square, Smile, LoyaltyLion); шаблоны и копирование конфигурации между tenant’ами (Open Loyalty); встраиваемые UI-компоненты с короткоживущей серверной сессией и feature-флагами (Stripe Connect embedded components); экономика партнёров — «оптовая цена + свобода наценки» (Kangaroo) или revenue share платформы (Shopify: 0% до $1M, далее 15%). Публичных «партнёрских usage-API» у loyalty-вендоров не найдено — метрики биллинга видны только как квоты планов.

### Cited Findings
**Контейнеры и изоляция**
- Talon.One: Application содержит кампании, API-ключи, сессии, профили; окружения sandbox/live; профили не видны между окружениями; кампании и активность нельзя шарить между Applications; одна loyalty program может обслуживать несколько Applications — [Talon.One: Applications](https://docs.talon.one/docs/product/applications/overview); [Talon.One: Loyalty programs](https://docs.talon.one/docs/product/loyalty-programs/overview)
- Voucherify: project — отдельные API-ключи и данные, используется по бренду/региону/валюте или для dev/staging — [Voucherify: Key concepts](https://docs.voucherify.io/get-started/key-concepts); число проектов зависит от плана (Business — 3, Organization — 5, Enterprise — custom), Enterprise — «Individual hosting» и private data hosting — [Voucherify pricing](https://www.voucherify.io/pricing)
- Open Loyalty: tenant (`storeCode`) с собственной БД участников, неизменяемой валютой и таймзоной; администраторы и роли — глобальные — [OL: Tenants](https://help.openloyalty.io/administration/settings/tenants.md)
- Capillary: иерархия Locations (business location → geographic/business grouping → point of transaction), coalition и multi-program — [Capillary docs index](https://docs.capillarytech.com/llms.txt)

**Провижининг через API**
- Voucherify Management API (Enterprise): все запросы на `https://{region}.voucherify.io/management/v1/`; управление projects, users (в т.ч. приглашение), metadata schemas, custom event schemas, stacking rules, webhooks, branding, campaign templates; до 5 management-ключей на организацию; токен можно скопировать в течение 15 минут; «The audit log does not record actions performed via the Management API for privacy and security reasons» — [Voucherify: Management API](https://docs.voucherify.io/guides/management-api)
- Заголовки Management API — `X-Management-Id` и `X-Management-Token`; пример — `POST /management/v1/projects/{projectId}/webhooks` (по сниппету) — [Voucherify: Create Webhook](https://docs.voucherify.io/api-reference/management/create-webhook)
- Talon.One Management API «allows you to programmatically do what the Campaign Manager does» — для бэк-офисных систем (по сниппету) — [Talon.One glossary](https://www.talon.one/glossary/application-programming-interface)
- Open Loyalty: копирование конфигурации между tenant’ами (wallets, custom event schemas, rewards, segments, achievements, campaigns, referral campaigns, automations), только внутри одного environment — [OL: Config duplication](https://help.openloyalty.io/global-management/config-duplication.md)

**Доступ сторонних приложений (marketplace / OAuth)**
- Square OAuth: code flow (confidential) и PKCE (public); «Square OAuth access tokens expire after 30 days»; refresh-токены code flow не истекают, PKCE — одноразовые и живут 90 дней; вебхук `oauth.authorization.revoked`; разные базовые URL для production и sandbox — [Square: OAuth overview](https://developer.squareup.com/docs/oauth-api/overview)
- Smile: приложения партнёров регистрируются в Partner Portal, скоупы read/write; при добавлении скоупов уже установившие мерчанты проходят OAuth повторно, «Smile Admin will automatically prompt users to reauthorize» — [Smile: Access scopes](https://dev.smile.io/guides/apps/auth/access-scopes.md); гайд миграции с API-ключей на OAuth — [Smile docs index](https://dev.smile.io/llms.txt)
- LoyaltyLion: вебхук-подписки скоупятся к OAuth-приложению (Client ID), подписываются секретом OAuth-клиента — [LoyaltyLion: Webhooks](https://developers.loyaltylion.com/api-reference/v2/webhooks/overview.md)
- Toast: партнёр получает Restaurant GUID и маппит ресторан в своей системе (по сниппету) — [Toast support](https://support.toasttab.com/en/article/Using-a-Gift-Card-Partner-Integration)

**White-label UI**
- Stripe Connect embedded components (эталон «встраиваемой админки» для платформ): сервер создаёт AccountSession для connected account и отдаёт браузеру `client_secret`; в сессии включаются конкретные компоненты и их фичи (например, `refund_management` только для админов — роль пользователя сайта нужно маппить на компоненты сессии); Connect.js создаёт custom elements (Web Components) или React-обёртки; кастомизация `appearance` (цвета, overlays), шрифты, `locale` (десятки локалей); сессия обновляется через `fetchClientSecret`, есть `logout`; требования CSP; компоненты не работают во встроенных WebView — для мобильных нужны нативные SDK — [Stripe: Connect embedded components](https://docs.stripe.com/connect/get-started-connect-embedded-components.md?platform=web)
- Smile UI — готовая панель и launcher, Smile.js — для кастомного UI — [Smile docs index](https://dev.smile.io/llms.txt)
- Antavo Display API — «the main headless API for building the customer loyalty experience» — [Antavo APIs](https://developers.antavo.com/docs/antavo-apis)
- Kangaroo: «a custom-branded mobile app», «fully tailored to your brand's look, feel, and tone», push, QR, геофенсинг — [Kangaroo: White-labelled app](https://loyalty.kangaroorewards.com/white-labelled-loyalty-app/)

**SSO и роли**
- Open Loyalty: SSO-вход в админку через Okta, Microsoft Entra ID и Auth0 — [OL docs index](https://help.openloyalty.io/llms.txt)
- Talon.One: «Audit logs, user roles & access levels» — уже в Starter-плане; «Unlimited users & webhooks» — в Enterprise — [Talon.One pricing](https://www.talon.one/pricing)
- Capillary: отдельный раздел RBAC в Loyalty+ — [Capillary: Loyalty+ overview](https://docs.capillarytech.com/docs/loyalty-overview.md)

**Партнёрская экономика и биллинг**
- Kangaroo Reseller: «100% Pricing freedom — set your own margins», «Receive wholesale pricing and mark up however you like», «Monthly Recurring revenue per active account», white-label и co-branding, «dedicated partner dashboard to manage all your accounts», «You close the deal — we handle onboarding, training, and ongoing client support», поддержка партнёров и клиентов 24/7 — [Kangaroo: Reseller partner program](https://loyalty.kangaroorewards.com/reseller-partner-program/); партнёры могут встраивать white-label движок Kangaroo в свою платформу через Open API (по сниппету) — [Kangaroo: Become a partner](https://loyalty.kangaroorewards.com/become-a-partner/)
- Shopify: разработчик сохраняет 100% первых $1 000 000 lifetime-выручки приложения и 85% сверх; регистрация $19; «All billing is subject to a 2.9% processing fee»; при >$20M годового дохода от приложений или >$100M выручки компании — 15% со всей выручки — [Shopify: Revenue share](https://shopify.dev/docs/apps/launch/distribution/revenue-share)
- Shopify App Pricing (рекомендуемый): планы задаются в форме сабмита, Shopify хостит страницу выбора плана и автоматизирует биллинг, trials, proration, апгрейды; поддержаны recurring и usage-charges, usage передаётся через App Events API; legacy — ручной Billing API (recurring, usage, one-time) — [Shopify: Billing](https://shopify.dev/docs/apps/launch/billing)
- Square монетизирует лояльность на стороне продавца: без активной подписки Square Loyalty запись через Loyalty API невозможна (404) — сторонний разработчик пользуется платной фичей продавца — [Square: Loyalty API overview](https://developer.squareup.com/docs/loyalty-api/overview)

### Inferences
- Рекомендуемая иерархия: Platform → Partner (ISV/реселлер/интегратор; собственные ключи, пользователи, брендинг) → Merchant/Tenant (валюта, таймзона, изоляция данных, sandbox + live) → Locations/Stores → Terminals/Channels (аналог Capillary «point of transaction»). Программа лояльности принадлежит мерчанту, но может шариться между его брендами/приложениями (как у Talon.One — одна программа на несколько Applications) и в коалициях.
- Две API-плоскости: runtime/integration (ключи на мерчанта, высокий QPS, idempotency) и management/provisioning (ключи партнёра: создать мерчанта, выпустить/отозвать ключи, вебхуки, шаблоны программ, пользователи, брендинг). В отличие от Voucherify, все действия management-плоскости нужно писать в аудит-лог.
- Для встраивания в собственные продукты создателя OAuth на каждого мерчанта избыточен: достаточно server-to-server токена партнёра + заголовка-идентификатора мерчанта (аналог `Stripe-Account`) с проверкой принадлежности мерчанта партнёру; для сторонних приложений (marketplace) — OAuth со скоупами, reauthorize при расширении скоупов и вебхук отзыва (Square/Smile).
- White-label-админка: встраиваемые Web Components + React-обёртки с короткоживущей сессией, выпускаемой бэкендом партнёра, и серверными feature-флагами/ролями на уровне сессии (паттерн Stripe) — это решает SSO «бесплатно» (партнёр уже аутентифицировал пользователя). Для покупателей — готовая панель/лаунчер (Smile UI) + headless API (Antavo Display API) + нативные SDK (WebView-ограничения Stripe показывают, что для мобильных нужен нативный путь).
- Шаблоны программ и копирование конфигурации (OL config duplication) — ключ к масштабированию на сотни SMB-мерчантов партнёра; при этом зависимости (тиры, сегменты, каналы) нужно копировать транзакционно.
- Партнёрский биллинг: платформа метрирует на уровне мерчанта (активные участники, заказы, локации, API-вызовы) и отдаёт партнёру usage-отчёт/API для перевыставления; коммерческие модели — оптовая цена + свободная наценка (Kangaroo) или revenue share (Shopify-подобно).

### Gaps
- Условия партнёрских программ Talon.One, Antavo, Open Loyalty, Voucherify (revenue share, скидки реселлерам) не найдены.
- Публичных API партнёрской usage-отчётности у loyalty-вендоров не обнаружено.
- SSO-передача сессии для мерчант-админов во встраиваемых сценариях (JWT handoff) у loyalty-вендоров не документирована; паттерн взят у Stripe.
- Детальная модель ролей партнёр/мерчант у Talon.One и Voucherify не исследована.

## 5. API-конвенции отрасли: calculate/preview vs commit, idempotency keys, версионирование, события/вебхуки, bulk import/export, пагинация, модель ошибок, OpenAPI и генерация SDK

### Takeaway
Де-факто стандарт отрасли: preview без побочных эффектов с передачей полной корзины → идемпотентный commit → явные reverse/return по строкам; idempotency по заголовку (Talon.One: 24 ч, ответные заголовки replay) или по бизнес-ключу (Antavo `transaction_id`, Square `idempotency_key`); датированное версионирование (Square `Square-Version: YYYY-MM-DD`, Voucherify `X-Voucherify-API-Version`, LoyaltyLion `/2025-06/` в пути); вебхуки с HMAC-SHA256, уникальным ID события, at-least-once и ретраями по экспоненте (от 30 попыток с отключением у LoyaltyLion до 12 попыток за 24 ч у Voucherify); отдельные async/bulk-каналы; ограничение глубокой пагинации; машиночитаемые ключи ошибок; SDK, генерируемые из OpenAPI, Postman-коллекции, а с 2026 г. — MCP-серверы.

### Cited Findings
**Preview vs commit**
- Talon.One: `dry=true` на обновлении сессии, «No data about the request or its response is stored», полная корзина на каждом dry run; commit — закрытие сессии — [Talon.One: best practices](https://docs.talon.one/docs/dev/integration-api/best-practices)
- Voucherify: qualification / validation (до 30 redeemables) → redemption → rollback — [Voucherify: Key concepts](https://docs.voucherify.io/get-started/key-concepts)
- Antavo: Points Preview API; pending checkout → `checkout_accept`/`checkout_reject` — [Antavo APIs](https://developers.antavo.com/docs/antavo-apis); [Antavo: API events](https://developers.antavo.com/docs/api-events.md)
- Square: CalculateLoyaltyPoints → AccumulateLoyaltyPoints; reward резервирует баллы до redeem/delete — [Square: Loyalty API](https://developer.squareup.com/docs/loyalty-api/overview); [Square: Loyalty rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards)
- Toast: LOYALTY_INQUIRE (многократно) → LOYALTY_REDEEM (при оплате) → LOYALTY_ACCRUE (асинхронно после оплаты) — [Toast: Transaction types](https://doc.toasttab.com/doc/devguide/apiLoyaltyTransactionDescriptions.html)
- Open Loyalty: campaign simulation как отдельная функция — [OL docs index](https://help.openloyalty.io/llms.txt)

**Возвраты и отмены**
- Talon.One: `POST /v2/customer_sessions/{id}/returns`, состояния partially_returned и cancelled, reopen — [TalonOne.cs IntegrationApi.md](https://raw.githubusercontent.com/talon-one/TalonOne.cs/master/docs/IntegrationApi.md); [Talon.One: Customer sessions](https://docs.talon.one/docs/dev/concepts/entities/customer-sessions)
- Antavo: `refund`, `partial_refund`, `refund_item`; сожжённые баллы восстанавливаются — [Antavo: API events](https://developers.antavo.com/docs/api-events.md)
- Open Loyalty: триггер Return Transaction; с июня 2026 возвраты автоматически отменяют связанные unit transfers — [OL: Trigger types](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/trigger-types.md); [OL: What's new 2026](https://help.openloyalty.io/whats-new/2026.md)
- Square: удаление ISSUED-награды возвращает баллы; для REDEEMED — только AdjustLoyaltyPoints — [Square: Loyalty rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards)
- Toast: LOYALTY_REVERSE откатывает REDEEM или ACCRUE по ID исходной транзакции — [Toast: Transaction types](https://doc.toasttab.com/doc/devguide/apiLoyaltyTransactionDescriptions.html)

**Idempotency и конкурентность**
- Talon.One: `Idempotency-Key` (≤255 символов, 24 ч), ответные `Idempotent-Replayed`, `X-Idempotency-Created-At/Expires-At/Fingerprint`; не для dry; параллельные обновления одной сессии/профиля → 409, их нужно сериализовать; read-after-write — подождать до 1 с — [Talon.One: best practices](https://docs.talon.one/docs/dev/integration-api/best-practices)
- Square: тот же ключ + тот же запрос → возвращается первый успешный ответ; тот же ключ + изменённый запрос → ошибка о повторном использовании ключа; рекомендуются UUID — [Square: Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
- Antavo: дубликат `transaction_id` → `ERR_TX_ALREADY_EXISTS` — [Antavo: API events](https://developers.antavo.com/docs/api-events.md)
- Toast требует идемпотентной обработки LOYALTY_SIGNUP от провайдера — [Toast: Transaction types](https://doc.toasttab.com/doc/devguide/apiLoyaltyTransactionDescriptions.html)

**Версионирование**
- Square: версии `YYYY-MM-DD`; у каждого приложения в Developer Console есть default-версия; переопределение заголовком `Square-Version`, ответ подтверждает версию; «Each Square SDK version is created for a specific API version»; жизненный цикл Beta → GA → Deprecated → Retired — [Square: Versioning](https://developer.squareup.com/docs/build-basics/versioning-overview)
- Voucherify: `v1` в URL + датированная версия (`X-Voucherify-API-Version`, текущая v2018-08-01), default — в Project settings — [Voucherify: Versioning](https://docs.voucherify.io/api-reference/versioning.md); вебхуки версионированы отдельно (v2024-01-01) — [Voucherify: Webhooks](https://docs.voucherify.io/reference/introduction-to-webhooks)
- LoyaltyLion: датированная версия в пути Headless API (`2025-06`) — [LoyaltyLion docs index](https://developers.loyaltylion.com/llms.txt)
- Talon.One: версии на уровне эндпоинтов сосуществуют (`/v1/...`, `/v2/events`, `/v3/events`) — [TalonOne.cs IntegrationApi.md](https://raw.githubusercontent.com/talon-one/TalonOne.cs/master/docs/IntegrationApi.md); в чек-листе рекомендует URL-версионирование и понятные пути депрекации — [Talon.One blog](https://www.talon.one/blog/evaluate-loyalty-api)

**События и вебхуки**
- Voucherify: HMAC SHA-256 в `x-voucherify-signature`, 12 ретраев до 24 ч, project-level и distribution-вебхуки — [Voucherify: Webhooks](https://docs.voucherify.io/reference/introduction-to-webhooks)
- LoyaltyLion: `x-loyaltylion-hmac-sha256`, ID для дедупликации, 200 за 5 с, после 30 неудач подписка удаляется — [LoyaltyLion: Webhooks](https://developers.loyaltylion.com/api-reference/v2/webhooks/overview.md)
- Open Loyalty: HMAC-подписи с марта 2026; события «X days before» (PointsWillExpire, CouponWillExpire, LevelWillExpire) — [OL: What's new 2026](https://help.openloyalty.io/whats-new/2026.md); [OL: Webhook triggers](https://help.openloyalty.io/integrations-and-data-exchange/webhooks/what-triggers-a-webhook.md)
- Square: loyalty-вебхуки по ресурсам (`loyalty.account.*`, `loyalty.program.*`, `loyalty.event.created`) + `oauth.authorization.revoked` — [Square: Loyalty API](https://developer.squareup.com/docs/loyalty-api/overview); [Square: OAuth](https://developer.squareup.com/docs/oauth-api/overview)
- Чек-лист Talon.One: ретраи, подпись, мониторинг доставки, out-of-order, уникальные ID — [Talon.One blog](https://www.talon.one/blog/evaluate-loyalty-api)

**Bulk, async, импорт/экспорт, пагинация**
- Antavo: bulk до 50 событий; Async Events API с correlation ID и порядком обработки — [Antavo: About Events API](https://developers.antavo.com/reference/about-events-api); [Antavo: Async Events API](https://developers.antavo.com/reference/about-async-events-api.md)
- Voucherify: bulk-обновления, async actions, экспорты/импорты — [Voucherify docs index](https://docs.voucherify.io/llms.txt)
- Talon.One: bulk-обновление профилей (`PUT /v2/customer_profiles`), синхронизация каталога (`PUT /v1/catalogs/{catalogId}/sync`) — [TalonOne.cs IntegrationApi.md](https://raw.githubusercontent.com/talon-one/TalonOne.cs/master/docs/IntegrationApi.md)
- Open Loyalty: импорт XML/CSV до 100 МБ, до 5 параллельных операций, AWS S3 exports; `_page` ≤ 500, дальше — scroll — [OL: Limits](https://help.openloyalty.io/technical-guide/api-fundamentals/limits); [openloyalty.io: API](https://www.openloyalty.io/technology/loyalty-program-api)

**Ошибки и лимиты**
- Voucherify: `{code, message, details, key}` + машиночитаемые ключи; 429 при превышении квоты — [Voucherify: Errors](https://docs.voucherify.io/api-reference/errors.md)
- Лимиты: Antavo 1 500 / 20 000 req/min (shared/dedicated stack) на ключ — [Antavo APIs](https://developers.antavo.com/docs/antavo-apis); Smile 10 req/s на токен — [Smile: Rate limits](https://dev.smile.io/api/rate-limits.md); Voucherify — по плану + 5 req/5 s на IP для client-side — [Voucherify: Limits](https://docs.voucherify.io/guides/limits); Open Loyalty — 40 RPM на логин — [OL: Limits](https://help.openloyalty.io/technical-guide/api-fundamentals/limits); Salesforce Loyalty Management — 50K/100K/500K API calls в день по редакциям — [Salesforce Loyalty pricing](https://www.salesforce.com/marketing/loyalty/pricing/)

**OpenAPI, SDK, инструменты разработчика**
- Voucherify — OpenAPI-based SDK — [GitHub: sdk-java-openapi-based](https://github.com/voucherifyio/sdk-java-openapi-based); Square — SDK привязаны к версиям API — [Square: Versioning](https://developer.squareup.com/docs/build-basics/versioning-overview); Talon.One — SDK на нескольких языках и Postman — [Postman: Talon.One](https://www.postman.com/talonone-rnd/talon-one/collection/3zq30db/-integration-api); Open Loyalty — Postman-коллекции и MCP-сервер (145 tools) — [openloyalty.io: API](https://www.openloyalty.io/technology/loyalty-program-api); [OL: MCP server](https://help.openloyalty.io/technical-guide/integration/mcp-server.md)
- Документация в машиночитаемом виде для LLM (`llms.txt`, `.md`-версии страниц) есть у Open Loyalty, Voucherify, Antavo, Capillary, Smile, LoyaltyLion — [OL](https://help.openloyalty.io/llms.txt); [Voucherify](https://docs.voucherify.io/llms.txt); [Antavo](https://developers.antavo.com/llms.txt); [Capillary](https://docs.capillarytech.com/llms.txt); [Smile](https://dev.smile.io/llms.txt); [LoyaltyLion](https://developers.loyaltylion.com/llms.txt)

### Inferences
- Рекомендуемый набор конвенций для новой платформы:
  - `POST /evaluate` (dry, полная корзина, без записи, параметр «now» для симуляции) → `POST /orders/{externalId}/commit` (требует `Idempotency-Key`; ответ с replay-заголовками как у Talon.One) → `POST /orders/{externalId}/returns` (по строкам) и `POST /orders/{externalId}/cancel`; награды — `reserve → redeem | release`.
  - Idempotency: заголовок для всех мутаций + уникальность бизнес-ключей (ID чека POS, `transaction_id`) как второй рубеж; хранить fingerprint запроса и возвращать ошибку при переиспользовании ключа с другим телом (Square).
  - Конкурентность: оптимистичные блокировки/версии на уровне сессии и участника, 409 с понятным кодом; документировать read-after-write задержку (или обеспечить read-your-writes).
  - Версионирование: датированные версии с pin-версией на уровне ключа/приложения и заголовком переопределения (Square/Voucherify); вебхуки версионировать отдельно; SDK — по версии API.
  - Вебхуки: каталог событий в прошедшем времени, `event_id`, `created_at`, `type`, `data`, HMAC-SHA256 заголовок, at-least-once, экспоненциальные ретраи ≥24 ч, автоотключение после N неудач с уведомлением, лог доставок и ручной replay; события-напоминания «X дней до сгорания баллов/тира».
  - Высокие объёмы: отдельный async ingest (correlation ID, порядок на участника), bulk до ~50–100 событий, асинхронные экспорт/импорт как job-ресурсы, cursor/scroll вместо глубокой offset-пагинации.
  - Ошибки: единый JSON с HTTP-кодом, машиночитаемым `key`, человекочитаемыми `message/details`, `request_id`; локализуемые сообщения для кассира/покупателя.
  - Лимиты: раздельно на чтение, запись и async, по ключу и по плану, с заголовками остатка; для публичных (client-side) ключей — лимит по IP и allowlist origin.
  - Developer experience: OpenAPI как источник истины → генерация SDK, Postman-коллекции, sandbox с паритетом, `llms.txt` и MCP-сервер.

### Gaps
- Точные политики депрекации (сроки) у Square/Voucherify не извлечены.
- Схемы cursor-пагинации у Voucherify/LoyaltyLion и заголовки rate-limit не исследованы.
- Формат ошибок Talon.One, Antavo, Square детально не извлечён.

## 6. Ценообразование (per member/MAU, per API call, per location, tiered, revenue share) и позиционирование 2025–2026: лояльность в CDP/CRM, AI-персонализация, «loyalty as a service»; взгляд аналитиков (Forrester, Gartner)

### Takeaway
Метрики цены чётко сегментированы: enterprise API-first — за активных участников (Open Loyalty, Antavo) или объём данных (Talon.One) либо за API-вызовы и проекты (Voucherify, от €600/мес); SMB e-commerce — за заказы в месяц с доступом к API только на средних тарифах (Smile.io $0–$999+, LoyaltyLion от $199, Yotpo от $199 + плата за заказ); POS — за локацию ($45–50/мес) или внутри пакета; CRM-сьюты — за организацию с квотами событий и API (Salesforce $20k–45k/мес); партнёрам — опт + наценка или revenue share. В Forrester Wave Loyalty Platforms Q4 2025 (11 вендоров, 27 критериев) лидеры — Epsilon, Kobie, Capillary; дифференциаторы — данные/идентичность участника, приватность, AI (predictive, generative, agentic) и сервисы.

### Cited Findings
**Модели цен (с цифрами)**
- Open Loyalty — по monthly Active Members (≥1 loyalty event в календарный месяц), Platform Fee + Allowance Fee, без ограничения функций — [openloyalty.io/pricing](https://www.openloyalty.io/pricing)
- Antavo — планы Start / Grow / Enterprise, «we charge based on customer activity. You won't be paying for customers that are not engaging with your stores»; цифры не публикуются — [Antavo pricing](https://antavo.com/pricing/)
- Talon.One — Starter / Professional / Enterprise; «all our pricing plans are based on your use of data volume»; Starter — «Individual pricing scheme with at least 500k coupons», staging environment и SDK library; webhooks и dedicated database server — с Professional; Enterprise — unlimited users & webhooks, customized SLAs — [Talon.One pricing](https://www.talon.one/pricing)
- Voucherify — Business €600/$650 в месяц (100 API calls/мин, 25 000 в месяц, 3 проекта), Organization €1 200/$1 300 (200/мин, 50 000, 5 проектов), Enterprise — custom (private hosting); 60-дневный trial; при превышении запросы могут быть «throttled or temporarily suspended», докупаются API-пакеты — [Voucherify pricing](https://www.voucherify.io/pricing); агрегаторы (по сниппетам поиска) приводят, по-видимому, устаревшие планы (Free 1 000 вызовов/мес, Startup $170, Growth $399, Professional $599) — расходится с официальной страницей — [Capterra](https://www.capterra.com/p/152431/Voucherify/pricing/); [SoftwareSuggest](https://www.softwaresuggest.com/voucherify/pricing)
- Smile.io — Free $0 (200 заказов/мес), Essential $15 (500), Standard $79 (1 000), Growth $199 (2 500), Plus $999 (7 500, годовая оплата; +$5 за каждые 100 заказов сверх), Enterprise — custom (без лимита заказов); API и «Front-end JavaScript SDK» — только Growth, Plus, Enterprise; VIP, рефералы, сгорание баллов, Shopify POS — на всех планах — [Smile pricing](https://smile.io/pricing)
- LoyaltyLion — Classic $199/мес (базово 500 заказов/мес), Advanced и Plus — custom; VIP-тиры на Classic — add-on; мультиязычность, баллы на карточке товара — с Advanced; AI-кампании, automated flows — Plus; Headless API — на всех планах — [LoyaltyLion pricing](https://loyaltylion.com/pricing)
- Yotpo Loyalty — Free $0; Pro от $199/мес за первые 500 заказов, далее $0,20 → $0,10 → $0,05 за заказ; Premium и Enterprise — custom; VIP-тиры — только Premium/Enterprise — [Yotpo Loyalty pricing](https://www.yotpo.com/pricing/loyalty/); вторичные источники называют Premium $799/мес до 3 000 заказов — расходится с официальным «custom» — [Rivo](https://www.rivo.io/blog/yotpo-loyalty-pricing)
- POS: Square ≈$45/мес за локацию или в Square Plus; Toast ≈$50/мес за локацию или бандл $185/мес; Lightspeed — в пакете Core ($149–179/мес) / во всех Restaurant-пакетах (вторичные источники; см. раздел 3) — [Loop Fans](https://loop.fans/blog/square-loyalty-program-review); [UpMenu](https://www.upmenu.com/blog/toast-pricing/); [Merchant Maverick](https://www.merchantmaverick.com/what-is-lightspeed-loyalty/)
- Salesforce Loyalty Management (лояльность внутри CRM-сьюта): Starter $20 000 за org в месяц (100 000 brand advocates, 1M событий/год, 50K API-вызовов/день), Growth $35 000 (15M событий/год, 100K API/день, одна программа), Advanced $45 000 (50M событий/год, 500K API/день, несколько программ); оплата ежегодно — [Salesforce Loyalty Management pricing](https://www.salesforce.com/marketing/loyalty/pricing/)
- Партнёрские модели: Kangaroo — оптовая цена и свобода наценки, MRR за активный аккаунт — [Kangaroo reseller](https://loyalty.kangaroorewards.com/reseller-partner-program/); Shopify — 0% до $1M lifetime, затем 15% — [Shopify revenue share](https://shopify.dev/docs/apps/launch/distribution/revenue-share)

**Аналитики**
- The Forrester Wave: Loyalty Platforms, Q4 2025 — отчёт RES188586 — [Forrester](https://www.forrester.com/report/the-forrester-wave-tm-loyalty-platforms-q4-2025/RES188586); опубликован 9 декабря 2025 г., оценены 11 провайдеров; Epsilon — Leader («one of only three»), максимальные оценки в 9 критериях, включая Customer & Member Profiles, Consumer Privacy, Supporting Services & Offerings; цитата Forrester: «Epsilon's solid vision of cross-channel personalization at scale, supported by the company's proprietary data assets…» — [Epsilon press release](https://www.epsilon.com/us/about-us/pressroom/epsilon-named-a-leader-in-loyalty-platforms-q4-2025-evaluation)
- Kobie — Leader и Customer Favorite, максимальные оценки в 21 из 27 критериев; цитаты Forrester: «A unique platform feature is its Agentic AI monitoring that reports accuracy across a host of metrics», «Kobie differentiates with data unification and identity management through its Panoramic Customer Profile™», AI-ассистент Bonnie™ — [Kobie](https://kobie.com/forrester-leader-2025/); [Business Wire, 10.12.2025](https://businesswire.com/news/home/20251210130649/en/Kobie-Named-a-Leader-and-a-Customer-Favorite-in-Loyalty-Platforms-Q4-2025-Evaluation)
- Capillary — Leader; по заявлению вендора — наивысшие среди 11 оценки по current offering и strategy и 5/5 в 22 из 27 критериев (заявление вендора, по сниппету; страница вернула 403) — [Capillary](https://www.capillarytech.com/forrester-wave-2025-loyalty-report/)
- Loyalty Juggernaut — Strong Performer — [LJI](https://lji.io/forrester-wave)
- Темы, которые Epsilon выделяет в связи с отчётом: identity resolution и обогащённые данные участника, predictive/generative/agentic AI, кросс-канальная персонализация, privacy-first, end-to-end оркестрация программ — [Epsilon press release](https://www.epsilon.com/us/about-us/pressroom/epsilon-named-a-leader-in-loyalty-platforms-q4-2025-evaluation)

**Тренды позиционирования 2025–2026**
- AI и агенты: MCP-сервер Open Loyalty (145 tools) — [OL: MCP server](https://help.openloyalty.io/technical-guide/integration/mcp-server.md); AI-кампании и рекомендации в LoyaltyLion Plus — [LoyaltyLion pricing](https://loyaltylion.com/pricing); Journey Catalyst (churn risk, spend lift, predictive reward matching) у Annex Cloud — [Annex Cloud](https://www.annexcloud.com/); CLV/churn/NBO у Comarch — [Comarch](https://www.comarch.com/trade-and-services/loyalty-marketing/); agentic AI monitoring у Kobie — [Kobie](https://kobie.com/forrester-leader-2025/); Antavo позиционируется как «AI Loyalty Cloud» (сторонний профиль) — [API Evangelist: Antavo](https://github.com/api-evangelist/antavo)
- Лояльность и CDP/CRM: Talon.One рекомендует держать golden customer record в CDP, а не в POS/ERP, и проверять синхронизацию аудиторий на продакшн-масштабе — [Talon.One blog](https://www.talon.one/blog/evaluate-loyalty-api); Salesforce продаёт Loyalty Management внутри CRM-платформы за org — [Salesforce pricing](https://www.salesforce.com/marketing/loyalty/pricing/)
- Лояльность внутри коммерческих/POS-платформ и бандлов: Square Plus, Toast Marketing-бандл, Lightspeed Core — см. раздел 3; Yotpo продаёт бандл Reviews + Loyalty (по сниппету) — [Yotpo bundle pricing](https://www.yotpo.com/pricing/bundle/)
- «Loyalty as a service» / white-label: Kangaroo — white-label движок и приложения для реселлеров и платформ — [Kangaroo reseller](https://loyalty.kangaroorewards.com/reseller-partner-program/); Open Loyalty — мультиарендность и коалиции — [openloyalty.io: Multitenancy](https://www.openloyalty.io/product/multitenancy)

### Inferences
- Для двойной модели новой платформы логично разделить ценовые метрики по каналам: (1) embedded в собственные POS/e-com создателя — фиксированный add-on за локацию/магазин в диапазоне рыночного якоря $45–50/мес либо включение в старший тариф основного продукта (как Square Plus/Lightspeed Core) ради ARPU и удержания; (2) standalone SaaS для SMB e-commerce — тарифы по заказам/мес с бесплатным входом и API/SDK на средних тарифах (Smile/Yotpo-модель); (3) mid-market/enterprise — platform fee + активные участники (OL/Antavo) с чётким определением «активного» и квотами API; (4) партнёры — оптовая цена со свободной наценкой или revenue share, с usage-отчётами по мерчантам.
- Метрика «активные участники» лучше всего связывает цену с ценностью и не штрафует за накопленную базу, но требует прозрачного определения и отчётности (у OL — ≥1 loyalty event в месяц); метрика «API-вызовы» (Voucherify) плохо подходит для embedded-сценария, где вызовы генерирует сама платформа.
- Чтобы попасть в «лидерский» набор по Forrester, недостаточно движка правил: нужны единый профиль участника с identity resolution и согласиями (privacy), AI-слой (прогнозы, генерация, агенты с мониторингом качества) и сервисная модель; для новой платформы минимально — профиль с consent-management и удалением данных (как `DELETE /v1/customer_data` у Talon.One), интеграция с CDP/аудиториями и AI-хуки (MCP, рекомендации наград).

### Gaps
- Исследования Gartner (Market Guide / Magic Quadrant по loyalty management) найти не удалось — веб-поиск исчерпан.
- Полный список 11 вендоров Forrester Wave Q4 2025 и точные критерии — за paywall.
- Сделки M&A в секторе лояльности 2025–2026 и G2-рейтинги не исследованы.
- Официальные цены Toast, Square, Clover и цены Comarch/Capillary/Annex Cloud/Kangaroo не получены (не публикуются или страницы недоступны).