# Get revenue SaaS metrics

`GET https://api.suger.cloud/org/{orgId}/revenue/dashboard/metrics`

Return SaaS revenue metrics for the organization over a date range, including ARR, MRR, and the ARR waterfall. Use this to report recurring-revenue KPIs and period-over-period movement.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `partner` | query | string | no | Channel filter (AWS, AZURE, GCP, STRIPE, or a CRM_* source). Use ALL or omit for every channel. |
| `startDate` | query | string | no | Start of the reporting range (RFC3339 or YYYY-MM-DD); defaults to 12 months before endDate |
| `endDate` | query | string | no | End of the reporting range (RFC3339 or YYYY-MM-DD); must be on or after startDate |
| `granularity` | query | string | no | Period granularity for the trend series (defaults to MONTH) |
| `allTime` | query | boolean | no | Start at the organization's earliest recurring contract |

## Responses

### 200 — OK

Content-Type: `application/json` · Schema: `RevenueDashboardMetricsResponse`

**`RevenueDashboardMetricsResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metrics` | RevenueMetrics | no |  |
| `periods` | array<RevenuePeriodMetrics> | no | Periods is the per-period decomposition at the requested granularity, oldest first, and at most 600 entries. Always present and never empty for a valid range: a period with no activity is returned with zero values rather than omitted. |
| `waterfall` | RevenueARRWaterfall | no |  |

**`RevenueMetrics`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activeCustomerCount` | integer | no | ActiveCustomerCount is the number of buyers with an active recurring contract at the range end date. |
| `arpu` | number | no | ARPU is average monthly revenue per active customer (MRR / activeCustomerCount). |
| `arpuByChannel` | object | no | ARPUByChannel is average monthly revenue per active customer, keyed by revenue channel. |
| `arr` | number | no | ARR is annual recurring revenue as of the range end date. |
| `byChannel` | object | no | ByChannel is monthly recurring revenue keyed by revenue channel (AWS, AZURE, GCP, STRIPE, ...). |
| `byCohort` | object | no | ByCohort is monthly recurring revenue keyed by the buyer's first recurring contract month, formatted YYYY-MM (for example 2026-03). |
| `byProduct` | object | no | ByProduct is monthly recurring revenue keyed by product ID. |
| `churn` | number | no | Churn is churned ARR as a percentage of the ARR twelve months before the range end date, over the same trailing twelve months as NRR. |
| `currency` | string | no | Currency is the ISO-4217 base currency every amount in this payload is expressed in. |
| `grr` | number | no | GRR is gross revenue retention as a percentage, over the same trailing twelve months as NRR. |
| `mrr` | number | no | MRR is monthly recurring revenue (ARR / 12). |
| `mrrTrend` | array<RevenueMetricSeries> | no | MRRTrend is the trailing twelve-month MRR series ending at the range end date. |
| `nrr` | number | no | NRR is net revenue retention as a percentage (100 means flat), measured over the trailing twelve months ending at the range end date. It is not scoped to the requested start date. |
| `nrrByChannel` | object | no | NRRByChannel is net revenue retention as a percentage, keyed by revenue channel. |

**`RevenuePeriodMetrics`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `arpu` | number | no | ARPU is average monthly revenue per active customer at the close of the period. |
| `churn` | number | no | Churn is ARR from buyers who were recurring at the opening and are not at the close. |
| `contraction` | number | no | Contraction is ARR lost by buyers who remain recurring at the close. |
| `currency` | string | no | Currency is the ISO-4217 base currency every amount in this period is expressed in. |
| `customerCount` | integer | no | CustomerCount is the number of buyers with an active recurring contract at the close. |
| `endingARR` | number | no | EndingARR is annual recurring revenue at the close of the period. |
| `expansion` | number | no | Expansion is ARR added by buyers who were already recurring at the opening. |
| `granularity` | string | no | Granularity is the period size requested for this decomposition. |
| `grr` | number | no | GRR is gross revenue retention for this period as a percentage. |
| `new` | number | no | New is ARR from buyers with no recurring contract at the opening. |
| `nrr` | number | no | NRR is net revenue retention for this period as a percentage. |
| `periodEnd` | string | no | PeriodEnd is the last day of the period, UTC, clamped to the requested end date for a final partial period. It carries the same time of day as PeriodStart, so treat the period as inclusive of this whole day. |
| `periodStart` | string | no | PeriodStart is the first day of the period, UTC. |
| `reactivation` | number | no | Reactivation is ARR from buyers returning after a lapsed contract. |
| `startingARR` | number | no | StartingARR is annual recurring revenue at the opening of the period. |

**`RevenueARRWaterfall`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `byChannel` | object | no | ByChannel independently applies the same buyer-level movement rules within each partner. A buyer moving between channels can therefore be churn in one channel and new/reactivated in another while remaining retained overall. Keyed by revenue channel (AWS, AZURE, GCP, STRIPE, ...). |
| `byCohort` | object | no | ByCohort decomposes components by the buyer's first recurring contract year-month (e.g. "2025-03"). |
| `churn` | number | no | Churn is ARR from buyers who were recurring at the opening and are not at the close. |
| `contraction` | number | no | Contraction is ARR lost by buyers who remain recurring at the close. |
| `currency` | string | no | Currency is the ISO-4217 base currency every amount here is expressed in. |
| `endingARR` | number | no | EndingARR is annual recurring revenue at the close of the range. |
| `expansion` | number | no | Expansion is ARR added by buyers who were already recurring at the opening. |
| `new` | number | no | New is ARR from buyers with no recurring contract at the opening. |
| `reactivation` | number | no | Reactivation is ARR from buyers returning after a lapsed contract. |
| `startingARR` | number | no | StartingARR is annual recurring revenue at the opening of the range. |

**`RevenueMetricSeries`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `color` | string | no | Color is the hex color the console chart draws this series in. |
| `data` | array<number> | no | Data holds one monthly value per period, oldest first. |
| `name` | string | no | Name is the series label: "Total MRR", "New MRR", "Expansion MRR" or "Churned MRR". |

### 400 — Invalid date, date range, or granularity

Content-Type: `application/json`

### 401 — Missing or invalid access token, or the caller lacks the revenue read permission

Content-Type: `application/json`

### 500 — Failed to calculate metrics

Content-Type: `application/json`

---

Interactive API reference: https://doc.suger.io/api/