GRR Definitions Book
The authoritative reference for Gross Revenue Retention calculations in the FoundryOps GRR Model Builder. Use this as the single source of truth for how metrics are computed.
Quick Navigation
1. What We Mean by GRR
Gross Revenue Retention (GRR) measures how much of the original "new customer revenue" is still retained over time, excluding expansions.
Key Principle: GRR curves in v1 are monotonically non-increasing by design. Reactivations do not increase GRR.
2. Core Entities
Customer (Logo)
A Customer is represented by a single Salesforce AccountId (18-char). All calculations are performed at the Account level.
Transaction Row
A source record from Opportunity orOpportunityLineItem. Transaction rows are used only for backend aggregation—they are not written to Sheets.
3. Time Model
| Term | Definition |
|---|---|
| CalendarMonth | First day of month (YYYY-MM-01) for stable bucketing |
| MonthsSinceCohort | Number of month boundaries between CohortMonth and CalendarMonth. Cohort month = 0. |
Note: All retention is computed at monthly resolution. Daily/weekly is out of scope for v1.
4. ARR Definitions
ARR Field
User-selected numeric/currency field from Salesforce Describe API.
ActiveARR (per Account, per CalendarMonth)
The total ARR considered "in force" for the account in that month.
- Includes renewals, expansions, and multiple products
- Computed from all extracted "won" ARR-bearing rows
- Calculated after applying service term logic and continuity rules
5. Extraction vs Acquisition (Critical)
Critical Separation: These two filters serve different purposes and MUST NOT be confused.
| Filter | Purpose | Scope |
|---|---|---|
| Extraction | Fetch ALL ARR-bearing records for ActiveARR | BROAD (IsWon = true, no Type filter) |
| Acquisition | Identify New Business for cohort + baseline | NARROW (e.g., Type = 'New Business') |
6. Cohort Assignment (Month 0)
Primary Rule (Default)
CohortMonth = first CalendarMonth where AcquisitionARR > 0
Fallback Rule (Optional, ON by default)
If no acquisition-qualified rows exist:
- CohortMonth = first CalendarMonth where ActiveARR > 0
- Set
CohortInferred = TRUE
7. BaselineARR (Denominator)
Why acquisition-only? This prevents Month 0 expansions from inflating the baseline. BaselineARR is frozen and applied to all subsequent months.
If CohortInferred = TRUE (no acquisition rows), then BaselineARR = ActiveARR in CohortMonth (fallback).
8. RetainedARR (Numerator)
This is account-level capping: expansions never increase retention above baseline.
Cohort Retention (Aggregate)
CohortRetainedARR_m = SUM(RetainedARR_m across accounts)
CohortBaselineARR = SUM(BaselineARR across accounts)
GRR_m = CohortRetainedARR_m / CohortBaselineARR
9. Continuity & Churn Policies
| Policy | Behavior |
|---|---|
| Strict | Any month with ActiveARR = 0 is churn (no smoothing) |
| Operational | Short gaps are bridged if within tolerance |
| Hybrid (default) | GRR uses smoothing; Logo churn reported under strict rules |
Gap Smoothing (Monthly Model)
Tolerance is applied as months, derived from days:
- 30-day tolerance = 1 month (bridges 1 consecutive zero-month)
- 60-day tolerance = 2 months (bridges up to 2 consecutive zero-months)
10. Terminal Churn (GRR Monotonicity)
Terminal Churn Rule: Once churned beyond tolerance, RetainedARR = 0 for ALL subsequent months.
- If ActiveARR returns later, it is counted as
ReactivationARR, NOT RetainedARR - This ensures GRR curves never increase over time
IsChurned = TRUEfrom churn month onward
11. Multi-Currency Handling
If Salesforce multi-currency is enabled, users must select one strategy:
| Strategy | Description |
|---|---|
| corporate_converted | User selects a converted/normalized currency field explicitly |
| normalized_field | User selects a custom normalized ARR field |
| single_currency_filter | User selects one CurrencyIsoCode (e.g., USD); others excluded |
If multi-currency is detected and no strategy is selected: BLOCK execution with a clear message.
12. Example Scenarios
Scenario A: Expansion Masking Churn
Baseline: $100K | M12 Active: $150K
Result: RetainedARR = MIN(150, 100) = $100K
The $50K expansion doesn't inflate retention.
Scenario B: Churn Then Reactivation
Baseline: $100K | M6: ActiveARR = $0 (churned) | M12: ActiveARR = $80K
Result: M12 RetainedARR = $0, ReactivationARR = $80K
GRR stays at 0% after churn. Reactivation tracked separately.
Scenario C: Month 0 Expansion
M0 New Business: $100K | M0 Expansion: $50K
Result: ActiveARR = $150K, BaselineARR = $100K, RetainedARR = $100K
Only New Business counts toward baseline.
What v1 Explicitly Does NOT Claim
- Does not guarantee reconciliation to finance books
- Does not resolve account merges or parent-child rollups
- Does not support CPQ subscription objects
- Does not compute NRR (expansion attribution)
- Does not do FX conversion beyond the chosen field/filter strategy
Ready to Build Your GRR Model?
Get started with the FoundryOps Sheets add-on and build your first cohort analysis in minutes.
Get the Sheets Add-on