Метрики

Где в админке

Список и карточка метрики: /billable-metric/*.
Журнал событий: /metric-events/*.

Типы метрик (логика API)

Тип	Назначение
Limit metered	Лимит потребления по подписке; при превышении новое событие может быть отклонено
Charge metered	Учёт usage; стоимость считается по тарифу на плане (фикс за единицу или ступени)
Charge recurring	Начисления по метрике в логике цикла (в т.ч. особые режимы агрегации, например max per day)

Точные числовые константы типов в коде API — в пакете метрик бэкенда; в документации для интеграции важнее семантика и привязка к плану.

Создание метрики

Создайте метрику в админке или через API (metricNew).
Укажите имя, описание, тип агрегации (сумма, последнее значение, максимум и т.д. — в зависимости от доступных полей в UI).
Для limit metered при необходимости задайте период сброса и группу лимитов (см. ниже).
При необходимости задайте скрипт постобработки (см. Шаблоны и скрипты).

Limit metered: период сброса

Для метрик типа limit metered usage считается внутри окна сброса. Поле limitResetPeriod задаётся при создании/редактировании метрики (metricNew / metricEdit) или в карточке метрики в админке.

Значение	Окно
`subscription_period`	Биллинг-период подписки (по умолчанию, обратная совместимость)
`hour`	Календарный час (`:00`–`:59`)
`day`	Календарный день (`00:00`–`23:59`)
`week`	Календарная неделя (ISO, с понедельника)
`calendar_month`	Календарный месяц

Границы часа, дня, недели и месяца — календарные, не скользящие. Timezone: user → merchant → UTC.

Metric Limit Grants (докупка пакетов, ручные гранты) работают только при limitResetPeriod = subscription_period.

В ответе userMetric для каждой limit-метрики в limitStats возвращаются limitResetPeriod, windowStart, windowEnd, windowResetsAt — чтобы продукт мог показать «осталось до сброса».

Limit group (несколько лимитов — один API-вызов)

Если нужны разные окна сброса одновременно (например, 1 000 в час, 10 000 в день, 100 000 в месяц), создайте несколько limit metered метрик с общим limitGroupCode:

Поле	Назначение
`limitGroupCode`	Общий код группы (slug: `[a-z0-9_]`, до 64 символов)
`limitGroupRole`	`primary` — принимает события через API; `member` — только учёт лимита

Правила:

В группе ровно один primary; member-метрики не принимают metricNewEvent напрямую.
У всех метрик группы одинаковые aggregationType и aggregationProperty.
Лимит на плане задаётся отдельно для каждой метрики группы.
Продукт шлёт один metricNewEvent с metricCode primary-метрики; BillBill атомарно проверяет все лимиты группы.

В админке: режим None (отдельная метрика) или In group с выбором группы из dropdown (GET /merchant/metric/limit_group/list).

Пошаговый рецепт с grants и докупкой пакетов: Токены и докупка пакетов.

Привязка к плану

На карточке плана задайте:

лимиты — какая метрика и какой потолок;
metered charge — цена за единицу или ступенчатый тариф (graduated);
recurring charge — правила рекуррентного начисления по метрике.

Данные сериализуются в структуру плана (поле уровня metricCharge в модели плана).

Отправка событий с вашего бэкенда

Используйте Merchant API metricNewEvent (или эквивалент в вашей версии клиента):

идентификатор метрики;
пользователь и контекст подписки;
значение инкремента / свойства агрегации;
при необходимости внешний идемпотентный ключ события.

События попадают в журнал; накопленное значение участвует в расчёте счёта.

Ограничения

Для лимитных метрик соблюдайте лимит до отправки тяжёлых операций у себя, иначе API вернёт ошибку при превышении.
События на member-метрику в limit group отклоняются — используйте код primary.
Скользящие окна (rolling 24h) в текущей версии не поддерживаются; доступны только календарные периоды из таблицы выше.
Частота событий и пики нагрузки — согласуйте с лимитами облака (см. Ошибки и dunning).

Если вам нужны ограничения без отправки usage в BillBill (например, retention или feature flags), используйте Policy-квоты, а не metered-метрики.