revenue.retention
Measures cohort revenue retention by anchoring customers at their first subscription event and reporting user retention plus net dollar retention at 7, 30, 60, and 90-day windows.
Instructions
Cohort revenue retention. Anchors each customer at their first cohort event (default: $subscription_started), then reports user retention + dollar retention at each anniversary window (default: 7d, 30d, 60d, 90d). Use this to answer "are customers sticking around?" and "is revenue churning, flat, or expanding?" in one round-trip.
Math is MRR-on-MRR: for each member, mrr_at_d is the cumulative sum of mrr_delta from anchor through anchor + d (the member's current MRR balance at that point). Retained members are mature members with mrr_at_d > 0. NRR = sum(mrr_at_d) / sum(baseline_mrr) across the same mature cohort — above 1.0 means net expansion (upgrades > churn), below 1.0 means contraction.
mature_size < size for windows the cohort isn't old enough to reach yet (e.g. a 90d window for a 30d-old cohort). Use mature_size to dim early windows or label them "cohort not yet mature".
Examples:
"what's our 30d retention" → read retention[].window=="30d".retention_rate (null when no mature members)
"are we expanding or contracting" → compare nrr across windows
"how many of last quarter's signups are still paying" → cohort_period="90d", read retention[].window=="90d"
Limitations: anchor is the user's FIRST cohort event in the period — re-subscribers after a cancel won't get a new anchor. The math assumes mrr_delta is set on $subscription_started / $subscription_canceled / plan-change events; events without mrr_delta don't affect the running balance. Canonical billing events are $-prefixed on the wire — pass cohort_event="$subscription_started" (not bare subscription_started) to anchor on them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| cohort_event | No | ||
| cohort_period | No | ||
| cohort_filter_property | No | ||
| cohort_filter_value | No | ||
| windows | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cohort | Yes | ||
| size | Yes | ||
| baseline_mrr | Yes | ||
| currency | Yes | ||
| retention | Yes |