> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Onboarding states

The `state` field on every onboarding holds one of three values: `active`, `paused`, or `done`. State is independent of `phase`. A paused onboarding can sit in any phase. The state controls what counts toward team capacity, what Pi watches, and what the customer sees in the portal.

## Active vs paused vs done

| Behavior                         | `active` | `paused`                    | `done`                        |
| -------------------------------- | -------- | --------------------------- | ----------------------------- |
| Counts toward CSM capacity       | Yes      | No                          | No                            |
| Pi risk alerts run               | Yes      | No                          | No                            |
| Target launch slippage tracked   | Yes      | Frozen at pause time        | Final value locked            |
| Phase moves allowed              | Yes      | No                          | No                            |
| Tasks can be edited              | Yes      | Yes                         | Read-only                     |
| Comments accepted                | Yes      | Yes                         | Yes                           |
| Visible in customer portal       | Yes      | Yes, with **Paused** banner | Yes, with **Launched** banner |
| Counts in on-time launch reports | Pending  | Pending                     | Yes                           |

## When to use each

**Active** is the default. Every new onboarding opens here. Leave it active as long as work is moving, even if it's slow. Pi handles slow.

**Paused** is for blocks coming from the customer's side: legal review, holiday freeze, key contact on leave. Pausing freezes the target launch date for slippage calculations and silences risk alerts. You're telling Pi "we're waiting, don't ping us." When the block clears, set the state back to active and the target launch shifts forward by the pause duration.

**Done** is terminal. The customer launched and adoption work, if any, lives in their [customer history](/product/customers/customer-history) from here on out. The onboarding becomes read-only. Tasks, comments, and the audit log stay intact.

## Changing state

Open the onboarding and click the **State** pill in the header.

* **Active > Paused** asks for a reason and an expected resume date. Both land on the audit log.
* **Paused > Active** is a single click. Pivotal recalculates the target launch slippage from the pause duration.
* **Active > Done** asks you to confirm the launch date. Pivotal sets `launched_at` to that date and stamps the on-time launch report. You can't go from paused to done; resume first.
* **Done > Active** is admin-only. The onboarding reopens and `launched_at` clears.

## Multiple onboardings, one customer

A customer can hold multiple onboardings in different states. Common pattern: one **done** onboarding for the initial product, one **active** onboarding for a second module. The [customer's health score](/product/customers/health-score) aggregates across all of them, weighted by recency.

## Gotchas

* Pausing doesn't pause notifications on tasks already due. If a task hits its `due_date` while the onboarding is paused, the assignee still gets the email. Adjust due dates when you pause if you don't want assignees getting pinged.
* A customer who's in [`at_risk` or `churned`](/product/customers/at-risk-and-churned) doesn't auto-pause their onboarding. Decide explicitly.
* The Workbench's default filter hides done onboardings. Add **State: done** to a saved view if you want to see them in your list.

## Related

* [Move through phases](/product/onboardings/move-through-phases)
* [Target launch dates](/product/onboardings/target-launch-dates)
* [At-risk and churned customers](/product/customers/at-risk-and-churned)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.