> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/platform/reporting-analytics.md).

# Insights

## Overview

Younium Insights is the analytics and reporting platform built into Younium. It provides dashboards, KPI widgets, and ad-hoc reports over your subscription, billing, and revenue data. Insights keeps its own copy of your Younium data, refreshed on a schedule, and serves it as queryable datasets through an OData API — to the Insights screens, and to external consumers. Reporting therefore never competes with day-to-day billing for resources, and the trade-off is that figures reflect the last refresh rather than the current second.

Insights supports multi-legal-entity analysis with currency consolidation, recurring revenue metrics (MRR, ARR, CMRR, CARR), revenue-change classification, invoicing and cashflow reporting, revenue recognition, and retention analysis. The platform applies tenant and legal-entity security filtering on every query so users see only the data they are authorised to access.

***

## Core Concepts

### Dashboard and widget

A dashboard is a composed view of Insights widgets — KPI cards, charts, tables, and other visual components. Widgets query one or more datasets with filters, grouping, and sorting applied. Dashboard layout and widget configuration are stored per tenant and served by the Insights API.

### Dataset

A dataset is a queryable view of your data, served through the Insights OData API. There are two families, covering the same figures:

| Dataset                                                        | What it is                                                                                                                                                                              |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Numbered datasets** (`DataSet1` – `DataSet20`)               | The datasets the Insights screens are built on, covering account-level figures, charge-level detail, bookings, revenue changes, invoicing, cash flow, revenue recognition and retention |
| **`RecurringRevenue`**, **`RevenueChanges`**, **`AllMetrics`** | The same figures with descriptive field names rather than numbered columns. Use these when querying the API directly                                                                    |

Each dataset applies tenant filtering and legal-entity filtering automatically. When a user has access to all legal entities, results span the full tenant. Otherwise, results are restricted to the user's authorised legal entities.

### Account segment

An account segment is a saved filter on account attributes (custom fields, country, account type, and other dimensions) that restricts which accounts appear in Insights widgets and reports. Segments let teams analyse subsets of their customer base — for example by region, industry, or customer tier — without rebuilding filters on every dashboard.

### Currency layers

Insights metrics are available in three currency layers:

| Layer                | Meaning                                                              |
| -------------------- | -------------------------------------------------------------------- |
| Original (no suffix) | Order or transaction currency                                        |
| Group (suffix `2`)   | Group currency — the default for dashboard display and consolidation |
| Base (suffix `3`)    | Legal-entity base currency                                           |

Monthly exchange rates from `T_ExchangeRatesMonthly` convert between layers. When comparing revenue changes across periods, currency movement is separated from real business change so FX effects do not appear as expansion or contraction.

***

## Key Metrics

### MRR (Monthly Recurring Revenue)

MRR is the normalised monthly value of recurring charges on active subscriptions. It is calculated at charge level from order product charges on last-version, non-draft orders.

| Characteristic   | Rule                                                           |
| ---------------- | -------------------------------------------------------------- |
| Source           | Order product charges with charge type Recurring               |
| Order status     | Active or Pending; OneOff charges may appear at later statuses |
| Version          | Last version of the order only                                 |
| Draft orders     | Excluded (`OrderNumber <> 'Draft'`)                            |
| Measured charges | Excluded                                                       |
| Usage charges    | Included only when flagged as Insights data                    |
| Discount         | Net MRR applies the order discount percentage for the month    |
| ARR              | MRR × 12                                                       |

MRR is expanded across calendar months between the charge start and end dates. Each month carries the charge's recurring amount adjusted for any applicable discount.

> **Note on usage recorded after its period was billed:** For a usage charge, a service period that has already been billed cannot pick up usage recorded afterwards — that usage cannot reach an invoice for the period it falls in. Insights excludes that usage from the period's MRR rather than counting it as revenue that will never be billed. Usage that was actually invoiced is still counted, and usage falling in the current, still-open period is counted as usual, since it remains eligible for the next invoice.

### Committed MRR and milestone MRR

Within MRR, charges are split by commitment type:

| Metric         | Meaning                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| CommittedMRR   | Recurring MRR from non-milestone charges                                                                  |
| MilestoneMRR   | Recurring MRR from milestone charges (charges with a planned start milestone but no effective start date) |
| AutoRenewalMRR | Forward projection of MRR from auto-renewed charges                                                       |

### CMRR and CARR (Contracted metrics from bookings)

CMRR (Contracted Monthly Recurring Revenue) and CARR (Contracted Annual Recurring Revenue) come from booking events rather than order charges. They reflect contracted revenue at the point a booking is recorded.

| Metric | Calculation                                  |
| ------ | -------------------------------------------- |
| CMRR   | Contracted monthly amount from booking lines |
| CARR   | CMRR × 12                                    |
| ACV    | Annual contract value from booking           |
| TCV    | Total contract value from booking            |
| OTF    | One-time fees from booking                   |

Rolling balances carry the last known CARR and CMRR forward into periods with no movement, which is what makes it possible to tell a customer who has gone quiet from one who has left.

### ACV, EMRR, and TCV (customer and subscription metrics)

These metrics appear in customer and subscription contexts:

| Metric | Meaning                              |
| ------ | ------------------------------------ |
| ACV    | Annual Contract Value                |
| EMRR   | Estimated Monthly Recurring Revenue  |
| TCV    | Total Contract Value                 |
| CMRR   | Contracted Monthly Recurring Revenue |

### One-time fees (OTF)

One-time fees appear in three contexts depending on the dataset:

| Context        | Source                                                   |
| -------------- | -------------------------------------------------------- |
| Bookings OTF   | One-time fees recorded on booking events                 |
| Charges OTF    | One-time fees from order product charges, month-expanded |
| Aggregated OTF | Charges-based OTF rolled up to account-month level       |

### Revenue changes

Revenue changes measure month-over-month movement in recurring revenue, classified into business-meaningful buckets:

| Classification   | Rule (previous month → current month)                       |
| ---------------- | ----------------------------------------------------------- |
| New customer     | Previous MRR = 0, current MRR > 0                           |
| Lost customer    | Previous MRR > 0, current MRR = 0                           |
| Expansion        | Current MRR > previous MRR (existing customer)              |
| Contraction      | Current MRR < previous MRR (existing customer)              |
| Ingoing balance  | Opening balance for the period                              |
| Index increase   | Revenue increase due to indexation (CMRR/CARR only)         |
| Correction       | Adjustments to contracted revenue (CMRR/CARR only)          |
| Volume expansion | Increase in volume from existing customers (CMRR/CARR only) |
| Merge Order      | Changes from merged orders (CMRR/CARR only)                 |
| Fx Effect        | Currency movement with no change in underlying value        |
| Usage            | Usage-based charge type                                     |

Change amounts are calculated on gross MRR: `MrrChange = current MRR − previous MRR` and `ArrChange = MrrChange × 12`. Group-currency variants subtract the FX-effect component.

> **Note on reactivation:** There is no separate reactivation bucket. An account whose MRR returns from zero to a positive value is classified as **New customer**.

### Retention

Retention metrics compare starting and ending MRR or CMRR balances over a trailing window (12-month or 3-month, tenant-configurable):

| Metric               | Calculation                                |
| -------------------- | ------------------------------------------ |
| Gross retention      | Starting MRR − churned MRR − downgrade MRR |
| Net retention        | Ending MRR                                 |
| Retention percentage | Amount ÷ starting MRR × 100                |

Losses are summed from Contraction and Lost customer classifications within the window.

### Recognised and deferred revenue

Recognised revenue and deferred revenue come from revenue schedule items per accounting period. These metrics support revenue recognition reporting separate from recurring revenue metrics. Charges flagged as non-Insights data are excluded from recognised revenue calculations.

***

## Behaviour and Rules

### Data extraction and refresh

Insights refreshes its copy of your data on a schedule, then republishes the datasets. Each dataset records when it was last updated, so you can confirm how current a figure is before acting on it — worth checking when a number disagrees with what you see on the underlying invoice or subscription.

### Multi-legal-entity reporting

When a user has access to multiple legal entities, Insights widgets can display consolidated results across entities or filter to a specific subset. Currency consolidation uses the group currency layer (suffix `2`) by default. Filters on legal entity, custom account fields, and order fields are available on most datasets.

### OData querying

The Insights API supports OData query parameters on all dataset endpoints:

| Parameter        | Purpose                                               |
| ---------------- | ----------------------------------------------------- |
| `$filter`        | Restrict rows by field conditions                     |
| `$orderby`       | Sort results                                          |
| `$top` / `$skip` | Pagination                                            |
| `$apply`         | Grouping and aggregation (groupby, aggregate, filter) |

External API consumers use the same OData syntax. String values in filters use single quotes; logical operators (`AND`, `OR`) are uppercase.

### Security filtering

Every query is restricted to your own tenant, and then to the legal entities the user is authorised for — all of them where the user has access to all, otherwise only those granted. Both restrictions are applied by Younium and cannot be widened by the client, including when querying the API directly.

***

## Configuration and Settings

Insights configuration is managed within the Younium application under the Insights navigation area. Operators configure dashboards, widgets, and account segments. No separate Insights admin application is required for standard use.

| Setting             | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| Dashboard layout    | Widget composition, filters, and visual configuration                    |
| Account segments    | Saved account filters for dashboard scoping                              |
| Legal entity access | Controlled by Younium user permissions                                   |
| Retention window    | 12-month or 3-month trailing window for retention metrics (tenant-level) |

Custom fields on accounts, orders, and order product charges appear as filterable dimensions in Insights datasets when configured in [Platform & Configuration](/platform/platform-configuration.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.younium.com/platform/reporting-analytics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.