> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Lifecycle

> How BuildBetter classifies where each account stands, where the classification comes from, and where it appears across Success

Every account BuildBetter knows about resolves to a **lifecycle** — a single classification of where that account stands commercially. Lifecycle is derived automatically from your billing and CRM data; it is not a field you set by hand.

<Info>
  Lifecycle is a cross-cutting classification, not a standalone page. It appears on [Follow-Ups](./follow-ups), [Customer Detail](./customer-detail), [Health](./health), and [Pipeline](./pipeline), and it is what "lifecycle" refers to in filters and rollups elsewhere in the product.
</Info>

## The Six Values

| Lifecycle           | Typical label                     | Means                               |
| ------------------- | --------------------------------- | ----------------------------------- |
| `paid_subscription` | Paid subscription / Paid customer | An active paying account            |
| `pipeline_open`     | Prospect                          | An open opportunity still in motion |
| `pipeline_won`      | Won                               | A closed-won opportunity            |
| `pipeline_lost`     | Closed lost                       | A closed-lost opportunity           |
| `churned`           | Churned                           | A former paying account that left   |
| `unknown`           | —                                 | Not enough data to classify         |

`unknown` is a real, expected state — an account BuildBetter has signals for but no billing or CRM record to place. It means "unclassified," not "broken."

## How It's Derived

BuildBetter resolves lifecycle from the strongest evidence it has, in roughly this order:

<Steps>
  <Step title="Billing and health data">
    An account with subscription data resolves to `paid_subscription`, carrying ARR, MRR, payment status, and the source that supplied them.
  </Step>

  <Step title="CRM pipeline data">
    An account with an opportunity resolves from its pipeline stage. The source stage is mapped to a **canonical stage** so different CRMs stay comparable.
  </Step>

  <Step title="Customer status fallback">
    Where neither is available, a stored customer status maps directly: `active_paying` to `paid_subscription`, `closed_lost` to `pipeline_lost`, `churned` to `churned`, `prospect` to `pipeline_open`.
  </Step>

  <Step title="Unknown">
    Nothing sufficient to classify leaves the account `unknown`.
  </Step>
</Steps>

## Canonical Pipeline Stages

Because every CRM names its stages differently, BuildBetter maps each source stage onto a canonical stage. Both are kept: the canonical stage for comparison and rollups, the original stage name so the account still reads the way your team talks about it.

| Canonical stage |
| --------------- |
| `prospect`      |
| `qualified`     |
| `proposal`      |
| `negotiation`   |
| `closing`       |
| `won`           |
| `lost`          |

<Tip>
  If an account's canonical stage looks wrong, the mapping from your CRM's stage is the thing to check — not the account. The original source stage is retained alongside it, which makes the two easy to compare.
</Tip>

## Lifecycle vs. Health

They answer different questions and can disagree:

* **Lifecycle** — the commercial state of the account. Are they paying, in pipeline, or gone?
* **[Health](./health)** — how the relationship is going right now.

A `paid_subscription` account can be unhealthy, and that combination is precisely what Success surfaces are built to catch. Reading only one of the two will hide it.

## Lifecycle Segments

Some surfaces — notably [Tracked Items](../Tracked/overview) and [Triage](../Triage/topics) — group accounts by **lifecycle segment**, a coarser bucket built on the same classification. Where you see counts broken out by segment, they roll up from the values above.

## Where It Comes From

Lifecycle quality is entirely downstream of your connected data:

* Connect a [CRM](../CRM%20Integration/overview) so pipeline stages and opportunity state are available.
* Keep company records linked, so signals attach to the right account.

Without either, most accounts resolve to `unknown` and lifecycle-based filtering has little to work with.

## Next

<CardGroup cols={2}>
  <Card title="Health" icon="heart-pulse" href="./health">
    How BuildBetter scores the state of a relationship.
  </Card>

  <Card title="Settings & Data" icon="gear" href="./settings-and-data">
    What Success needs connected to work well.
  </Card>
</CardGroup>