# How trials and grace periods work

**For:** Admin
**You'll need:** Owner role on the tenant.

This article explains the lifecycle: when {{ app_name }} considers your subscription **trialing**, **active**, in **grace**, **suspended**, or **cancelled**, and what changes when each state flips.

## States

- **Trialing** — your tenant is on a free trial. Everything works exactly like a paid plan.
- **Active** — you have a valid subscription and the most recent invoice was paid.
- **Grace** — payment failed (or the trial ended without a payment method). The tenant keeps working for a short window so you can fix billing without losing data.
- **Suspended** — the grace window ran out without a successful charge. Members can sign in but most write actions are blocked. Reading and exporting data still works so you can leave cleanly if you choose.
- **Cancelled** — the subscription was cancelled in the Stripe Billing Portal. The tenant stays active until the end of the period it's already paid for; after that it falls into grace, then suspension.

## What drives state changes

Two things change the state:

- **Stripe webhooks** — every time something happens in Stripe (a charge succeeds, a charge fails, a subscription is cancelled), Stripe pings {{ app_name }} and the state is updated immediately.
- **The billing-lifecycle background job** — runs periodically and walks expired trials and grace periods, applying the next state when a deadline has passed.

You don't trigger either — they happen on their own.

## How to fix a failed payment

1. Open billing (account dropdown → **'Account'** → **'Billing'**).
2. Click **'Manage billing'** to open the Stripe Billing Portal.
3. Update the payment method.

The next charge attempt usually happens within minutes. When it succeeds, the tenant flips back to **'Active'**.

## Verify it worked

Open billing. The status badge on your tenant should read **'Active'**. Members can use {{ app_name }} normally.

## Related

- {doc}`start-a-subscription`
- {doc}`manage-billing`
- {doc}`/settings-and-admin/tenants/delete-a-tenant`