Analytics
The analytics endpoints expose pre-aggregated billing metrics that would otherwise require expensive ad-hoc queries against the underlying invoice and subscription tables. Three metric families are currently exposed: MRR, churn, and a revenue breakdown.
Why this matters. Decisions about pricing, retention, and growth depend on metrics that finance, ops, and product all trust - bespoke SQL against the billing database loses that trust the moment definitions diverge across teams. Kontorion exposes pre-aggregated, definition-aligned metrics so the same numbers reach the dashboard, the boardroom, and the customer.
Available metrics
| Metric | Endpoint | What it answers |
|---|---|---|
| MRR | GET /v1/analytics/mrr | Monthly recurring revenue history. |
| Churn | GET /v1/analytics/churn | Logo (customer-count) churn for the current period. |
| Revenue breakdown | GET /v1/analytics/revenue | Revenue grouped by plan (default), or by customer type. |
All three sit under the BearerAuth security scheme and use the standard data envelope (see Errors for the response shape).
MRR history
Code
| Query param | Default | Notes |
|---|---|---|
currency | (required) | 3-letter ISO 4217 code (e.g. EUR, USD). The endpoint filters and labels every amount for this single currency. Omitting it returns 400 with field currency, code REQUIRED; a non-3-letter value returns field currency, code INVALID_FORMAT. |
months | 12 | History length, in months. Capped at 36; values outside 1..36 fall back to 12. |
segment | unset | When set to customer_type, returns the breakdown by BUSINESS / CONSUMER / UNKNOWN. |
Response shape (segmented variant). currency labels every amount; aggregate is the combined series, and segments[] carries one entry per customer type. All amounts are major-unit decimal strings:
Code
The unsegmented variant drops aggregate/segments and returns a flat object — currency, current, previous, change_rate, and a time_series of { month, value } points:
Code
Churn
Code
Returns logo (customer-count) churn for the period the analytics service computes against. The response carries current_rate and previous_rate (each a 0..1 rate), churned_count (customers churned this period), and total_customers (active customers). Churn is currency-agnostic and takes no request parameters.
Revenue breakdown
Code
| Query param | Default | Notes |
|---|---|---|
currency | (required) | 3-letter ISO 4217 code (e.g. EUR, USD). The endpoint filters and labels every amount for this single currency. Omitting it returns 400 with field currency, code REQUIRED; a non-3-letter value returns field currency, code INVALID_FORMAT. |
segment | unset | Default groups revenue by plan — each breakdown[] item carries plan_id, plan_name, revenue, and count (subscription count). Set to customer_type to instead group by customer type, returning segments[] of { customer_type, revenue, invoice_count }. |
Both variants are wrapped in the data envelope and carry currency plus a total, with each amount as a major-unit decimal string (e.g. { "value": "94200.00", "currency": "EUR" }).
Caching and freshness
Analytics aggregates are computed asynchronously off the billing event stream and surfaced at request time from materialized rollups. The exact freshness window depends on workspace size and the upstream sync cadence; treat values as eventually consistent.
Monetary amounts are returned as major-unit decimal strings wrapped in the standard Money envelope — { "value": "49.50", "currency": "EUR" } — not minor units (cents). Time-series points (time_series[].value) are bare major-unit decimal strings labelled by the response's currency field.
MRR and revenue are filtered to the single currency you pass in the required currency query parameter; there is no fixed organization base currency, and the response's currency field always echoes the code you requested. Amounts already recorded in that currency are summed directly — see Exchange rates for how cross-currency conversion is handled at finalize time. Churn is currency-agnostic (it counts customers) and takes no currency parameter.
- Subscriptions - the entity MRR aggregates over.
- Segments - planned cohort surface (roadmap).