# Lifecycle stage, lead status and pipelines

Facts checked against HubSpot's live docs on 2026-10-17.

## Three questions, three fields

- Lifecycle stage answers "what is our relationship with this person or company?" It lives on contacts and companies. Default labels: Subscriber, Lead, Marketing Qualified Lead, Sales Qualified Lead, Opportunity, Customer, Evangelist, Other. Read the internal values in the portal before mapping imports or integrations; do not assume they equal the labels.
- Sales follow-up state answers "is someone working this, and where are they?" Use one of:
  - The Lead status contact property, when the team works contacts directly. Read its current options in the portal; accounts customise them.
  - The leads object, on Sales Hub Professional or Enterprise, when reps prospect from the sales workspace. Leads have their own pipeline stages and must have a primary association with a contact or company. Activation needs a Super Admin; creating leads from the contacts index or sales workspace needs an assigned Sales seat.
  - Not both for the same state. If the leads object is adopted, retire or redefine Lead status and say so in `decisions.md`.
- Deal stage answers "how far has this one opportunity progressed?" It lives on deals, per pipeline.

Keep other operational facts out of lifecycle: subscription status, churn status, payment risk and temporary follow-up states get their own properties. A former customer stays Customer in relationship history while `subscription_status` says cancelled.

## Transition evidence

Write one line per transition: from, to, evidence, who or what sets it, and the timestamp that counts as entry.

Illustrative set for a B2B SaaS (fictional; replace with the team's agreed rules):

```yaml
lifecycle:
  lead:
    evidence: Valid identified person with a sales or marketing interaction
    set_by: Form default stage or workflow
  marketing_qualified_lead:
    evidence: Fit rule passed and an engagement threshold met, as defined in metrics.md
    set_by: Workflow
  sales_qualified_lead:
    evidence: Rep confirmed use case, authority and a next step
    set_by: Rep, through lead status or the leads object
  opportunity:
    evidence: A deal exists in a sales pipeline
    set_by: Lifecycle setting "set lifecycle stage when a deal is created"
  customer:
    evidence: Closed won deal, or billing system reports an active paid subscription
    set_by: Lifecycle setting on deal won, or the billing integration
```

A booked meeting alone is not qualification. A direct demo request deserves a response even when a score is low; eligibility and priority are separate rules.

## How HubSpot moves lifecycle

- Default automatic updates only move lifecycle forward.
- Imports, form submissions, the API, the Salesforce integration and workflows only move the default property forward. To set an earlier stage with those tools, clear the value first (manually or in a workflow), then set the new value.
- A manual backward move clears the legacy "Became a [stage] date" for the higher stage. The calculated "Date entered [stage]" and "Date exited [stage]" properties are not cleared.
- "Latest time in [stage]" and "Cumulative time in [stage]" need Professional or Enterprise. While a record is in a stage they have no value unless it was in that stage before (then they show the earlier time), and cumulative time updates only when the record leaves.

Lifecycle automation settings live at Settings > Data Management > Objects > Contacts (or Companies) > Lifecycle Stage tab, under Pipeline Rules and Automate. Decide and record each one:

- Set lifecycle stage when a contact or company is created.
- Sync lifecycle stages: a contact follows its primary company's stage when the company is first associated as primary and when the company's stage changes. A contact's change does not update the company.
- Set lifecycle stage when a deal is created (first associated deal).
- Set lifecycle stage when a deal is won.
- Set lifecycle stage when a lead is associated. This does not fire when an automation created the lead.

None of these settings moves a stage backward. With the Salesforce integration, its "Automatic lifecycle stage transitions" setting applies to all HubSpot contacts associated with the same company.

## Designing the correction path

Because the forward-only rule applies to imports and workflows, plan corrections now:

- A governed workflow, enrolled manually by an admin, that clears lifecycle then sets the corrected value, with a `lifecycle_correction_reason` property.
- Never fix lifecycle by re-importing a file: unchanged rows will look like success.
- Before any correction, read property history and the reports that count stage entries. A correction changes conversion rates.

## Reporting on stages

- Use "Date entered [stage]" for entry and "Date exited [stage]" for exit. Decide how re-entry is counted (first entry only, or every entry) before building a funnel.
- Put the counting unit in every report title: contacts, companies or deals.

## Pipelines and stage evidence

- Each pipeline represents one sales motion with its own stages. A second pipeline is justified when stages or owners genuinely differ (new business versus renewals), not to separate regions that share a process.
- The custom pipeline limit is shared across all objects. Read the count in Data Management > Data Model > Limits. On 2026-10-17 the docs listed 15 for Starter, 100 for Professional and 350 for Enterprise on seat-based subscriptions, and 350 for Professional and Enterprise on flexible seats-and-credits; re-check before relying on it.
- For each stage record:
  - Entry evidence in plain words.
  - Required properties. Conditional stage properties marked required stop a user who creates a record in the stage or moves one into it by hand until they are set. HubSpot documents this for manual creates and moves in the UI; imports, integrations, workflows and API writes are not documented as blocked. Test each writer that can place a deal in the stage.
  - A saved view or report per stage listing deals with a required property empty. It is the real control for deals placed by imports and integrations; check it daily during the observation period.
  - Win probability. Closed Won (100) and Closed Lost (0) must exist under deal probability; probability drives the weighted amount.
  - Internal ID. Hover the stage in pipeline settings to copy it. Imports, integrations and the API use it.
  - Who may move a deal into it and which automation reacts.
- Editing pipelines needs Edit property settings permission.
- Deleting a stage that still holds records is blocked until those references are removed. Plan stage changes as migrations: move records, update integrations that reference the old ID, then delete.
- Do not add stages for product usage or marketing qualification. A customer trying a feature is not a new opportunity.

## Validation differs by writer

Stage and property validation is not enforced the same way everywhere. Imports, integrations, workflows and the API are not documented as checking required stage properties, and HubSpot's assistant connectors differ in which validation rules they apply (see the connector pages in `sources.yaml`). Test a write that should be rejected in each tool and client the team uses before trusting stage rules as a control.