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

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.