API: Billing

Subscription, usage and checkout. Cloud-only — in MODE=onprem these routes are not mounted and return 404. The signed on-prem max_events_month is currently contract metadata; runtime event-quota enforcement is backlog.

Кому: Разработчики, интегрирующие ActionPulse по HTTP
Проверено: 28.07.2026

На этой странице

GET /billing
POST /billing/cancel
POST /billing/checkout
GET /billing/details
PUT /billing/details
PUT /billing/email
POST /billing/invoice
GET /billing/invoices/{id}
POST /billing/payment-method/detach
GET /billing/usage
POST /billing/webhook
GET /email/unsubscribe
POST /email/unsubscribe

Раздел собран из спецификации OpenAPI продукта: 13 метод(ов). Поверхность — query-api (основной API, база /api/v1). Без токена доступа доступны 3 из 13.

Методы раздела

GET /billing
POST /billing/cancel
POST /billing/checkout
GET /billing/details
PUT /billing/details
PUT /billing/email
POST /billing/invoice
GET /billing/invoices/{id}
POST /billing/payment-method/detach
GET /billing/usage
POST /billing/webhook
GET /email/unsubscribe
POST /email/unsubscribe

GET /billing

Get subscription, access state and available plans (cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: getBilling

Cloud-only. In MODE=onprem this route is not mounted (404).

Ответы

Код	Что означает	Тело
200	Subscription and plans. `subscription` is null if none; `plans` is always present (a fresh org sees the pricing grid).	`BillingResponse`
401	Missing or invalid credentials (code=unauthorized)	`Error`
404	Not mounted in on-prem mode	`Error`

POST /billing/cancel

Cancel the active subscription (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: postBillingCancel

Cloud-only. In MODE=onprem this route is not mounted (404).

Ответы

Код	Что означает	Тело
204	Cancellation scheduled	пусто
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Not mounted in on-prem mode	`Error`
422	Request failed validation (code=validation_failed)	`Error`

POST /billing/checkout

Start a checkout for a plan (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: postBillingCheckout

Cloud-only. In MODE=onprem this route is not mounted (404).

Тело запроса application/json , обязательно

Поле	Тип	Описание
`plan` обязательно	`string`	Plan code

Ответы

Код	Что означает	Тело
200	Hosted YooKassa redirect	`object`
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Not mounted in on-prem mode	`Error`
422	Request failed validation (code=validation_failed)	`Error`

GET /billing/details

Get the org's legal details for invoicing (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: getBillingDetails

Ответы

Код	Что означает	Тело
200	Billing details	`BillingDetails`
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Not mounted in on-prem mode, or details not filled in yet	`Error`

PUT /billing/details

Set the org's legal details for invoicing (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: putBillingDetails

Тело запроса application/json , обязательно

Поле	Тип	Описание
`inn` обязательно	`string`	10 (org) or 12 (sole trader) digits
`kpp` обязательно	`string`	Empty for sole traders
`name` обязательно	`string`
`legal_address` обязательно	`string`

Ответы

Код	Что означает	Тело
204	Saved	пусто
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Not mounted in on-prem mode	`Error`
422	Request failed validation (code=validation_failed)	`Error`

PUT /billing/email

Set the billing email for fiscal receipts and invoices (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: putBillingEmail

Cloud-only. Required before the first checkout: fiscal receipts (54-FZ) need a recipient email. In MODE=onprem not mounted (404).

Тело запроса application/json , обязательно

Поле	Тип	Описание
`email` обязательно	`string (email)`

Ответы

Код	Что означает	Тело
204	Saved	пусто
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Not mounted in on-prem mode	`Error`
422	Request failed validation (code=validation_failed)	`Error`

POST /billing/invoice

Issue a B2B invoice for a paid plan (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: postBillingInvoice

Creates a pending payment (kind=invoice) and an HTML invoice «PP-{id}» (print styles; browsers print to PDF), also emailed to the billing email. Requires billing details and billing email. The subscription activates/extends after a platform admin confirms the bank transfer (POST /admin/payments/{id}/confirm). Quarterly and yearly invoices apply the current catalog term discount. Yearly payment extends period_end by 12 months; auto-renewal is NOT enabled.

Тело запроса application/json , обязательно

Поле	Тип	Описание
`plan_code` обязательно	`string`
`months` обязательно	`enum(1, 3, 12)`

Ответы

Код	Что означает	Тело
200	Invoice issued	`object`
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Not mounted in on-prem mode	`Error`
422	Request failed validation (code=validation_failed)	`Error`

GET /billing/invoices/{id}

Download an issued invoice as an HTML file (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: getBillingInvoicesId

Параметры

Имя	Где	Тип	Описание
`id` обязателен	Путь	`integer (int64)`

Ответы

Код	Что означает	Тело
200	Invoice document (Content-Disposition attachment)	`string`
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`

POST /billing/payment-method/detach

Detach the saved payment method (owner; cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: postBillingPaymentMethodDetach

Cloud-only. Clears the saved YooKassa payment method locally (YooKassa offers no detach API for regular shops); auto-renewal stops because the recurring charger skips subscriptions without a saved method. In MODE=onprem this route is not mounted (404); 404 is also returned when there is no subscription or nothing to detach.

Ответы

Код	Что означает	Тело
204	Payment method detached	пусто
401	Missing or invalid credentials (code=unauthorized)	`Error`
403	Authenticated but not permitted (code=forbidden)	`Error`
404	Resource not found (code=not_found)	`Error`

GET /billing/usage

Get month-to-date usage and access state (cloud-only)

Аутентификация: Bearer: токен доступа (JWT)
operationId: getBillingUsage

Cloud-only. Plan metadata is absent when there is no current effective plan. In MODE=onprem this route is not mounted (404).

Ответы

Код	Что означает	Тело
200	Usage	`BillingUsageResponse`
401	Missing or invalid credentials (code=unauthorized)	`Error`
404	Not mounted in on-prem mode	`Error`

POST /billing/webhook

YooKassa payment webhook (public, cloud-only)

Аутентификация: Без аутентификации
operationId: postBillingWebhook

Public endpoint (no JWT). A complete Basic-auth credential pair is mandatory; the optional source-IP allowlist is an additional restriction and never replaces credentials. Source IP is derived from the direct TCP peer, not forwarding headers. Cloud-only. Always returns 200 once authenticated so that YooKassa does not retry.

Тело запроса application/json , обязательно

Схема тела: object.

Ответы

Код	Что означает	Тело
200	Processed (also returned for ignorable notifications)	пусто
401	Missing or invalid credentials (code=unauthorized)	`Error`
422	Request failed validation (code=validation_failed)	`Error`

GET /email/unsubscribe

Marketing unsubscribe confirmation page (public, cloud-only)

Аутентификация: Без аутентификации
operationId: getEmailUnsubscribe

Public endpoint (no JWT). Authorized by the HMAC-signed token embedded in the marketing email link. Returns an HTML confirmation form; the actual opt-out happens on POST so that mail-client link prefetch cannot unsubscribe a recipient without their action. An invalid or tampered token returns 400. Cloud-only.

Параметры

Имя	Где	Тип	Описание
`token` обязателен	Query	`string`	HMAC-signed unsubscribe token from the email link.

Ответы

Код	Что означает	Тело
200	HTML confirmation form	`string`
400	Invalid or tampered token (HTML page)	`string`

POST /email/unsubscribe

Record a marketing email opt-out (public, cloud-only)

Аутентификация: Без аутентификации
operationId: postEmailUnsubscribe

Public endpoint (no JWT). Authorized by the HMAC-signed token. Writes the recipient email into the marketing opt-out list (idempotent — a repeat is a no-op). Transactional trial emails are unaffected. An invalid or tampered token returns 400. Cloud-only.

Тело запроса application/x-www-form-urlencoded , обязательно

Поле	Тип	Описание
`token` обязательно	`string`	HMAC-signed unsubscribe token from the email link.

Ответы

Код	Что означает	Тело
200	Opt-out recorded (HTML confirmation page)	`string`
400	Invalid or tampered token (HTML page)	`string`

Источник раздела — docs/api/openapi.yaml репозитория продукта, версия API 1.0.0, OpenAPI 3.0.3, снимок 095579325c2d. Расхождение снимка со спецификацией роняет сборку документации.

← Все разделы API Reference