> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouclay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics

> MRR, churn, retention and cohorts, worked out from your billing data

> [!NOTE]
>
> Early access. Write to [hello@bouclay.com](mailto:hello@bouclay.com) to have it turned on for your account.

Bouclay works out your subscription metrics from the same data it bills from, so the numbers match your invoices. See them in the dashboard under **Metrics**, or read them through the API.

## Terms

* **MRR** (monthly recurring revenue): what your live subscriptions bill per month, with yearly plans divided by 12. It counts `active` and `past_due` subscriptions (a failed payment is owed, not lost), and leaves out trials, pauses, usage charges, one-off charges and VAT.
* **ARR**: MRR × 12.
* **Net revenue retention (NRR)**: of the revenue you had from customers a while ago, how much you have now, upgrades included. Above 100% means existing customers grow faster than they leave.
* **Gross revenue retention (GRR)**: the same, without counting upgrades. It shows only what you lost.

## Current MRR

```bash theme={null}
curl https://bouclay.com/api/v1/metrics/mrr \
  -H "Authorization: Bearer $BOUCLAY_KEY"
```

Returns MRR and ARR for each currency you sell in.

## The monthly report

```bash theme={null}
curl "https://bouclay.com/api/v1/metrics/report?currency=NGN&months=12" \
  -H "Authorization: Bearer $BOUCLAY_KEY"
```

For each calendar month (UTC), the current one running to now, it explains how MRR moved:

```text theme={null}
start + new + expansion − contraction − churn + reactivation = end
```

| Movement | Means |
| - | - |
| `new` | Customers paying for the first time. |
| `expansion` | Existing customers paying more: an upgrade, more seats. |
| `contraction` | Existing customers paying less. |
| `churn` | Customers who stopped paying. |
| `reactivation` | Customers who left and came back. |

Movements are counted per customer, so a customer who swaps one subscription for another is expansion or contraction, not churn plus new. The report also includes retention and cohorts: how much of each month's new customers' revenue is still there in later months.

The `metrics` scope gives a restricted key read access to both.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.