> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconrevenue.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Churn risk — who might leave, why, and how much time is there to act?
> How Churn risk reads each paying customer's facts, what it produces today, what you see on its page, what it needs, which modules depend on it, and what it does not calculate yet.
**Churn risk** answers one question: *Who might leave, why, and how much time is there to act?* Every morning it reads each paying customer's facts from your billing — its revenue, how long it has been with you, its cancellations and downgrades over the last year, its next renewal date — and the signals noticed on it, and groups them by size, industry and segment. It belongs to the Customer family — see [Modules](/modules/overview).
This page describes the module as it runs today. Each customer's facts — monthly revenue and ARR, time with you, cancellations and downgrades in the last twelve months, next renewal date and signals in the last 90 days — are live. **Churn risk — the score from 0 to 100 for each customer — and everything built on it: its tier, its main driver, ARR at risk, retention probability, days to likely churn and the alerts, is designed and not calculated yet.** How each of the score's five layers turns what Beacon reads into a number from 0 to 100 is not yet written down, and two of the layers have no source connected in most companies. The rules the live facts follow are set out [below](#the-facts-produced-today).
## What it does
A customer rarely leaves without warning. Use thins out, support tickets pile up, payments slow, a downgrade comes before the cancellation. Churn risk is built to score every customer for the risk of leaving, name what drives that risk, say whether it is the kind a retention play can fix, and, for the customers most at risk, estimate how many days are left to act.
Today it does the part that needs no score. Once a day, after your billing has loaded and Usage intelligence has run, it:
* **Lists every paying customer** — every customer with recurring revenue last month — and says how many of the customers Beacon holds for you that is.
* **Reads last month's recurring revenue** for each one, and its ARR.
* **Works out how long each one has been with you**, from its first subscription start: first 3 months, months 3 to 12, after the first year — or renewing within 90 days, once a renewal date is recorded.
* **Counts cancellations and downgrades** on each customer's subscriptions over the last twelve months, and the monthly revenue they took.
* **Reads each customer's next renewal date**, where your billing records one.
* **Counts the signals noticed** on each customer in the last 90 days.
* **Groups the customers** — all of them, each size group, each industry and each segment — with their revenue, time with you, cancellations, downgrades and signals.
* **Keeps a month-end picture** of every customer, written once after each month closes and never changed, so each customer's risk can be followed month by month once it is scored.
Beacon reads your billing, your CRM and your product analytics. It never writes into them, and it never contacts a customer.
## What it produces
Its headline is four figures. None is calculated yet.
| KPI | What it measures | Today |
| - | - | - |
| [**Churn risk**](/definitions/churn-risk) | Each customer's risk of leaving, from 0 to 100 — higher means more risk — with its tier: Low, Moderate, Elevated, High or Critical | Not calculated yet — how each of the five layers becomes a score is not written down |
| **ARR at risk** | The ARR of customers whose churn risk is High or Critical (70 and over) — the figure the page leads with, by size group | Not calculated yet — waits for churn risk. The page shows **—**, never the whole ARR |
| **Retention probability** | The chance each customer is still with you in 12 months and in 24 months | Not calculated yet — waits for churn risk |
| **Days to likely churn** | For High and Critical customers only: how many days are likely left before the customer leaves, between 14 and 180, with how sure the estimate is | Not calculated yet — waits for churn risk |
Churn risk links to its definition, which also says how the [Data API](/api-reference) and [MCP](/mcp-tools) will carry it — neither serves it yet. The other three get their definitions when they are calculated.
Behind them it also produces:
| What | What it tells you | Today |
| - | - | - |
| **Paying customers** | How many of your customers had recurring revenue last month, out of all the customers Beacon holds for you | Produced daily |
| **Monthly revenue and ARR** | Last month's recurring revenue for each customer and each group, from your billing, and ARR as 12 times that | Produced daily |
| **Time with you** | Each customer's start date, and how many customers are in their first 3 months, months 3 to 12, after their first year, and renewing within 90 days | Produced daily — renewing within 90 days needs renewal dates |
| **Cancellations and downgrades, last 12 months** | For each customer: how many of its subscriptions were cancelled or downgraded, and the monthly revenue they took — see [churned](/definitions/churn-mrr) and [contraction](/definitions/contraction-mrr) revenue | Produced daily |
| **Next renewal date** | The next date each customer comes up for renewal, and how many subscriptions carry one — see [Renewal date](/definitions/renewal-date) | Produced daily, where your billing records one |
| **Signals, last 90 days** | How many signals were noticed on each customer — see [Signals](/modules/signals) | Produced daily |
| **Month-end picture** | Each customer's facts and time with you as they stood at each month end | Written once a month, after the month closes |
| **Monthly revenue and what was lost** | Your recurring revenue at each month end over the last twelve months, and the revenue lost that month to cancellations and to downgrades | Shown, from your company revenue rows |
| **Usage in the last two weeks** | Customers whose use of your product rose, held or fell, by segment | Shown, read from [Usage intelligence](/modules/usage-intelligence) |
| **The five layers** | Engagement, health and support, commercial signals, lifecycle economics and customer fit, each from 0 to 100 | Not calculated yet |
| **Tier** and **main driver** | Each customer's tier, and the layer that drives its risk | Not calculated yet |
| **Alerts** | Six rules — became High, became Critical, month 3 still recoverable, a segment getting riskier, models disagree, and structural risk | Described, none sent |
## How it is worked out
### The facts produced today
These are counts and sums of what your billing and your other modules record, worked out by fixed, written rules — the same data always gives the same figures. The page itself works nothing out: it shows what the morning run wrote.
* **Who counts.** Every customer Beacon holds for you whose recurring revenue last month adds up to more than zero. A customer that stops paying drops out of the list; its earlier rows are kept, never deleted.
* **Last month.** The calendar month before the run. Not the latest month in your billing, because a billing schedule can hold rows for months ahead.
* **Monthly revenue** is the sum of the customer's recurring revenue for last month, in your reporting currency. **ARR** is 12 times that.
* **Customer since** is the earliest start date among the customer's subscriptions.
* **Time with you** is counted in whole months from that date to the end of last month: *first 3 months* under 3, *months 3 to 12* under 12, *after the first year* from 12. A customer whose next renewal falls within 90 days of the end of last month reads *renewing within 90 days* instead. These four are Churn risk's own until Customer lifecycle places customers in its stages; then Churn risk is to read those.
* **The last twelve months** are last month and the eleven before it. A **cancellation** is a subscription cancelled; a **downgrade** is a subscription moved to a lower amount. Each is counted as your billing records it, with the monthly revenue it took. A pause counts as a cancellation, then a return.
* **Next renewal date** is the earliest renewal date on the customer's subscriptions on or after the end of last month. Empty when none is recorded.
* **Signals** are counted over the 90 days up to the latest signal noticed — not up to the run day, so a late signal run does not shrink the count.
* **Segment** is the customer's confirmed segment when it has one; otherwise its size group and industry together. Usage intelligence groups customers the same way.
* **The month-end picture** is written by the first run after a month closes, one row per paying customer, and never rewritten.
The run starts at 09:00 UTC, after the billing load and Usage intelligence.
### How churn risk will be worked out — designed, not calculated
Each customer is scored on five layers, each from 0 to 100, then weighted and added up. Higher means more risk.
| Layer | Weight | What it will read | In your tools today |
| - | - | - | - |
| **Engagement and adoption** | 30% | Use against the customer's own recent level, features dropped, days since last real use, milestones behind its segment — usually the strongest single sign | Partly — Usage intelligence's read of each customer's use; its own score is not calculated yet |
| **Health and support** | 25% | Tickets and their severity, escalations, satisfaction scores, an executive sponsor going quiet — often weeks before use falls | Not read yet — needs a support desk |
| **Commercial signals** | 20% | Days to pay and missed payments, billing disputes, downgrades, growing discounts — payment behaviour can show trouble 30 to 60 days before use does | Partly — cancellations and downgrades; invoices and payments are not loaded |
| **Lifecycle economics** | 15% | The customer's forward value falling — 10 points or more in 90 days | Not yet — Lifecycle economics is not built |
| **Customer fit** | 10% | The risk part of how well the customer fit at signing, so a strong-fit customer under brief stress does not look like a weak-fit one | Not yet — the fit score is not calculated |
The weights move a little with time with you: onboarding, adoption, maturity and the renewal window.
**Tiers.** *Low* — under 35. *Moderate* — 35 to 54, worth watching. *Elevated* — 55 to 69, act early while it is cheap. *High* — 70 to 84, counted in ARR at risk. *Critical* — 85 and over, the VP of Customer Success steps in. The lines are the same across Beacon; changing them needs the VP of Customer Success and the CFO.
**Main driver.** For each customer at 55 and over, the layer that gives more than 35% of its score — or *Mixed signals* when none does, with the two largest named.
| Main driver | Kind | What usually follows |
| - | - | - |
| **Engagement decline** | Recoverable | Adoption coaching, with customer education on the features it stopped using |
| **Health and support distress** | Recoverable | A root-cause look at the support pattern with the support lead, beyond closing tickets |
| **Commercial signals** | Recoverable | Fix the billing or payment issue; talk about the plan before renewal |
| **Lifecycle economics decline** | Structural | A keep-or-let-go decision from Lifecycle economics, not the standard save play |
| **Structural fit** | Structural | Usually a do-not-retain review; the lesson goes back to who is sold to |
| **Mixed signals** | — | The owner decides |
**The rules.**
* **One extreme layer** — if any one layer reaches 90, the score is at least 70, so a single alarm is never averaged away.
* **Days to likely churn** — only at 70 and over, between 14 and 180 days, with how sure it is. Set from how fast the score is rising, how long customers in the segment usually take from High to leaving, and how close the renewal is.
* **Retention probability** — the chance a customer is still with you in 12 and 24 months, from its score and segment. Learned from your own customers once a segment has 50 that left or renewed after a year; until then an estimate across companies, labelled so.
* **Less certain** — in a customer's first 30 days, or when its record fails the integrity check, the score is marked as less certain.
* **Recalculated** — every morning, and within the hour of a big change: usage down 25% in a week, an escalation, a missed payment, a satisfaction score moving, a contract change, or Lifecycle economics moving 10 points.
* **Confirmed and reviewed** — the VP of Customer Success confirms the month-end picture on the first working day. Every quarter the weights are checked against which customers actually left; a change of 5 points or more also needs Beacon's review.
* **Overrides** — the VP of Customer Success or the owner can override a score, with the reason and when to look again. Repeated overrides are looked at in the quarterly review.
* **Flags, never decides** — Churn risk does not decide to keep or let a customer go. High and Critical customers go to Lifecycle economics for that verdict, and a person decides.
None of this is calculated today. How each layer turns what Beacon reads into a score from 0 to 100 is not yet written down; the health and support layer has nothing to read until a support desk is connected and read; payments are not loaded; and Lifecycle economics and the fit score do not exist yet. Until then, the page shows each customer's real facts and says **Not yet calculated** for the score.
## What you see on its page
In Beacon, open **Customers** under Growth and choose **Churn risk**, under *Keep & grow*. The banner leads with **ARR at risk** for each size group — it reads **—** until churn risk is calculated, with each group's customers and ARR beneath as context — and names the next tool to connect. The page has six tabs:
* **Overview** — what each of the five layers can read in your tools today; customers with a cancellation or downgrade in the last twelve months; how many customers renew within 90 days; the customers to act on and the drivers, each waiting for the score; how the score is built; who it is for; its data sources; what it reads from and feeds; and where it shows up.
* **Dashboard** — the module's six charts — customers by tier now and a year ago, ARR at risk month by month, who is at risk by kind of customer, risk against customer fit, what drives the risk, and churn predicted against churn that happened — each saying what it waits for; then three charts from your real data: monthly revenue and what was lost over the last twelve months, usage in the last two weeks by segment, and customers by time with you per size group.
* **Signals & alerts** — what the module watches and what it has seen so far, and its six alert rules with what each waits for.
* **Scorecard** — the five layers and their weights, the tiers, time with you, the drivers and the rules.
* **Customers** — every paying customer, filterable by size, industry and time with you, with its segment, time with you, usage over the last two weeks, next renewal date and ARR. Churn risk reads *Not yet calculated*. Select a customer for what its tools show for each layer and what scoring it still needs.
* **Setup** — the module's questions, the connections it uses, and the company questions it shares with the rest of Beacon.
The page reads **Not measured yet** until your CRM is connected, **Coming** until the first morning run has written, and **Running with gaps** once it has. It does not read **Live** yet, because churn risk is not calculated.
## What it needs
| Tool | | What it adds | Checked today |
| - | - | - | - |
| **Billing** (Stripe) | Must be connected | Beacon runs no module without billing. Here it gives every fact the module produces today: revenue, start dates, cancellations, downgrades and renewal dates | Yes |
| **CRM** (HubSpot) | Needed to start | Your customer records, size groups, industries and owners — and where churn risk will show on each company | Yes — the page reads Not measured yet without it |
| **Product analytics** (PostHog) | Adds detail | How each customer uses your product, through Usage intelligence — the largest layer | Yes — the last two weeks of use |
| **Support desk** | Adds detail | Tickets, severity, escalations and ratings — the health and support layer, a quarter of the score | Not read by Churn risk yet |
| **Payments** | Adds detail | Late and failed payments, from your billing's invoices — part of the commercial layer | Not loaded yet |
| **Customer success platform** | Adds detail | Health scores, satisfaction and sponsor engagement, if you use one | Not read yet |
| **Accounting** | Later | Days to pay and margin per customer | Not read yet |
See [Connect your tools](/connect-your-tools) for how each connection is made.
## Reads from
| Module | What Churn risk uses it for |
| - | - |
| [**Data model**](/modules/data-model) | Your customers, their subscriptions and their recurring revenue, joined into one record each — read today |
| [**Segments**](/modules/segments) | Each customer's confirmed segment, to group customers — read today. Later, each segment's usual churn rate, the starting point for a new customer |
| [**Signals**](/modules/signals) | How many signals were noticed on each customer — read today. Later, payment, billing, support and usage signals feed the health and commercial layers |
| [**Usage intelligence**](/modules/usage-intelligence) | Each customer's use over the last two weeks — read today. Later, usage health is 30% of the score |
| [**Data integrity**](/modules/data-integrity) | A layer drawn from a record that fails the integrity check counts for less, and the score is marked as less certain — not read yet |
| [**Customer fit**](/modules/customer-fit) | The risk part of each customer's fit, 10% of the score — not read yet |
| [**Segment revenue paths**](/modules/segment-revenue-paths) | How each segment's revenue usually holds up, for new customers — not read yet |
| [**Contract intelligence**](/modules/contract-intelligence) · **Pipeline velocity** | What each customer signed for, and how long a new customer usually takes to get going — not read yet |
| **Lifecycle economics** · **Cost to serve** | Whether a customer's forward value is falling, and whether it costs more and more to serve — not read yet |
| **Cash flow** · **Margin** | Payment behaviour and margin per customer, once accounting is connected — later |
## Which modules read it
| Module | What it uses Churn risk for |
| - | - |
| **Cost to serve** · **Customer value** · **Prices and discounts** · **Sales acquisition cost** | Each paying customer's facts as Churn risk writes them — who is paying, last month's revenue, start date and segment — read today |
| [**Forecast confidence**](/modules/forecast-confidence) | How many subscriptions there are and how many carry a renewal date — read today |
| **Lifecycle economics** | Retention probability sets each customer's remaining lifetime margin; churn risk is 20% of its score |
| **Customer revenue forecast** | The main input to each customer's renewal chance |
| **Expansion readiness** | High-risk customers are not expansion candidates, whatever else says they are ready |
| **Customer value** | Later, the main risk discount on each customer's value |
| **Revenue forecast** | How much renewal revenue is safe and how much is at risk |
| [**Signals**](/modules/signals) | Every quarter, which signals came before customers that left — so signals get sharper |
| [**Deal likelihood**](/modules/deal-likelihood) · [**Segment revenue paths**](/modules/segment-revenue-paths) | Each segment's churn rate, for renewal deals and for how steeply each segment's path falls away |
| **Acquisition cost** | Churn risk of each sign-up group at months 3, 6 and 12 — the quality of each channel |
Cost to serve, Customer value, Prices and discounts, Sales acquisition cost and Forecast confidence read Churn risk's live facts today. Everything else reads the score, its tier, its driver or retention probability, which are not calculated, so it receives nothing from this module yet. The **Modules** page in The Brain shows which modules are running for you.
## Alerts
Six alert rules are described.
| Alert | When it fires | Goes to |
| - | - | - |
| **Became High** | A customer's churn risk crosses 70 from below. Urgent if the likely churn is under 60 days away, it renews within 90 days, or its remaining lifetime value is above the amount set in Setup | Customer success owner and VP of Customer Success — HubSpot and Slack |
| **Became Critical** | A customer's churn risk crosses 85. Urgent, whatever the days to likely churn: a 24-hour review and a keep-or-let-go decision within 48 hours | Customer success owner and VP of Customer Success — Slack and email |
| **Month 3, still recoverable** | At month 3 a customer is Elevated (55 to 69) and its main driver is engagement or support — the cheapest moment to fix it. A play within 14 days | Customer success owner — HubSpot |
| **A segment is getting riskier** | A segment's average churn risk moves 5 points or more month on month, two months running | VP of Customer Success, CMO and CFO — Slack and email |
| **Models disagree** | Churn risk and Lifecycle economics, or retention and renewal chance, disagree by more than 15 points. Automatic steps on the customer pause. Urgent | VP of Customer Success and the RevOps lead — Slack and email |
| **Structural risk** | A High customer whose main driver is lifecycle economics or customer fit — reviewed for a deliberate do-not-retain decision | VP of Customer Success — HubSpot |
**No alert is sent yet.** Four wait for the score, *A segment is getting riskier* waits for two months of scores, and *Models disagree* waits for Lifecycle economics. Who gets the alerts is picked from your Beacon users in Setup; every alert also goes to the customer's owner in HubSpot. Churn risk never contacts a customer or changes anything in your tools.
## Setup questions
* **Where are your customers' renewal dates?** Needed for the renewal window and for how soon churn could happen. Recommended: the billing period end on your Stripe subscriptions. Other answers: a contract end date in HubSpot; on the contracts, read by Contract intelligence.
* **Where does Beacon read support and customer health?** A quarter of the score. Without it that layer is filled from your segment's usual rate and the score is marked as less certain. Recommended: connect your support desk. Other answers: HubSpot tickets; you have no support tool.
* **How should Beacon tell a customer's stage?** Recommended: from time since signing and the renewal date. Other answers: a lifecycle stage field in HubSpot; Customer lifecycle, once its stages are placed.
* **Do the standard lines fit your customers?** High at 70, Critical at 85, Low under 35. Recommended: keep them. Other answers: review after the first month; propose your own lines.
* **How far ahead should days to likely churn look?** Recommended: 14 to 180 days. Other answers: 14 to 365 days, for long yearly renewals; 7 to 90 days, for monthly plans.
* **From what remaining lifetime value is a High customer always Urgent?** In your reporting currency. Recommended: 50,000. Other answers: 25,000; 100,000.
* **Run a dry run before the first alerts go out?** Recommended: yes — customers are scored but nothing is sent until the VP of Customer Success has checked the spread. Other answer: switch on straight away.
* **Who owns churn risk and its alerts?** The VP of Customer Success, with the CFO agreeing changes to the lines, picked from your Beacon users. Not available on the page yet.
The first seven are saved from the Setup tab. Today's facts do not depend on them; they are used once churn risk is scored. How you segment your customers, how you handle onboarding and support, and your reporting currency are asked once, in Company DNA.
## What is not calculated yet
* **Churn risk** for each customer, its **five layers**, its **tier** and its **main driver**.
* **ARR at risk**, **retention probability** and **days to likely churn**.
* **The six score charts** on the Dashboard, including churn predicted against churn that happened.
* **Support, payments and satisfaction** — not read by Churn risk yet.
* **Alerts** — none is sent yet.
* **Churn risk through the Data API, MCP, events and your CRM** — defined on the [account object](/data-model/account), not served yet.
## Related
The ten module families and which modules are available today.
The score from 0 to 100, its five layers, its tiers and what it is not.
How each customer uses your product — the largest layer of churn risk.
What changed for each customer, and which signals come before churn.
When each customer comes up for renewal — the anchor for the renewal window.
Recurring revenue lost from customers who went to zero.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.