revenue.retention
Shows whether customers are sticking around by tracking cohort retention and net revenue retention. Anchors each user at their first subscription event and reports retention rates at set windows, revealing churn or expansion.
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 |
|---|---|---|---|
| windows | No | ||
| 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_value | No | ||
| cohort_filter_property | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | Yes | ||
| cohort | Yes | ||
| currency | Yes | ||
| retention | Yes | ||
| baseline_mrr | Yes |