***

title: Subscription lifecycle
subtitle: >-
Understand how subscriptions move through states from creation to
cancellation, and how payment outcomes drive automatic transitions.
-------------------------------------------------------------------

# Subscription states

Every subscription exists in one of seven states. PaymentKit automatically transitions subscriptions between states based on payment outcomes and scheduled events.

| State          | Description                                                                                                       |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Incomplete** | Subscription created but awaiting initial payment. The first invoice may not yet be paid.                         |
| **Scheduled**  | Subscription is scheduled for a future start date. Transitions to Trialing or Active when the start date arrives. |
| **Trialing**   | Free trial period is active. No charges until the trial ends.                                                     |
| **Active**     | Normal billing cycle. Invoices are generated and payments collected on schedule.                                  |
| **Past due**   | A payment has failed. The dunning system retries collection automatically.                                        |
| **Paused**     | Billing is temporarily suspended. No invoices are generated while paused.                                         |
| **Cancelled**  | Subscription is terminated. No further billing occurs. This is a terminal state.                                  |

## Key transitions

| From       | To        | Trigger                                                               |
| ---------- | --------- | --------------------------------------------------------------------- |
| Incomplete | Trialing  | Trial period begins                                                   |
| Incomplete | Active    | First payment succeeds                                                |
| Incomplete | Cancelled | Payment fails or manual cancel                                        |
| Scheduled  | Trialing  | Start date arrives and trial period begins                            |
| Scheduled  | Active    | Start date arrives (no trial)                                         |
| Trialing   | Active    | Trial ends and payment succeeds                                       |
| Trialing   | Paused    | Pause requested during trial                                          |
| Trialing   | Cancelled | Cancel requested during trial                                         |
| Active     | Active    | Renewal payment succeeds                                              |
| Active     | Past due  | Payment fails                                                         |
| Active     | Paused    | Pause requested (immediately or at period end)                        |
| Active     | Cancelled | Cancel requested (immediately, at period end, or on a scheduled date) |
| Past due   | Active    | Payment recovered                                                     |
| Past due   | Cancelled | Dunning exhausted                                                     |
| Paused     | Active    | Resume requested (manually or auto-resume)                            |
| Paused     | Trialing  | Resume requested and trial period not yet expired                     |
| Paused     | Cancelled | Cancel requested                                                      |

# How transitions work

PaymentKit uses a lifecycle engine that continuously evaluates the subscription's state and determines the next action. The engine runs automatically after each state change.

## Billing cycle

At the end of each billing period, the lifecycle engine:

1. Creates a draft renewal invoice
2. Finalizes the invoice
3. Attempts payment collection
4. On success: advances the billing period and schedules the next cycle
5. On failure: transitions the subscription to **Past due** and begins dunning

## Trial period

When a subscription has a trial:

1. Subscription starts in **Trialing** state
2. Three days before the trial ends, a `subscription.trial_will_end` event fires
3. At trial end, the subscription transitions to **Active** and the first paid invoice is generated

<Tip>
  Listen for the `subscription.trial_will_end` webhook event to notify customers before their trial expires.
</Tip>

## Payment failure and dunning

When a payment fails on an active subscription:

1. The subscription moves to **Past due**
2. PaymentKit retries payment on a smart schedule (first retry within 1 hour, then every 4 days)
3. Dunning emails are sent to the customer with a link to update their payment method
4. If all retries fail, the configured dunning end behavior applies (cancel subscription, mark invoice uncollectible, or keep open)

See [Automatic retries & emails](/guides/billing/auto-retries-emails) for details on retry schedules and configuration.

## Pausing and resuming

Subscriptions can be paused immediately or scheduled to pause at the end of the current billing period. While paused, no invoices are generated and no payments are collected.

When a paused subscription resumes:

* A prorated invoice is created for the remaining time in the current period
* Payment is attempted on the prorated invoice
* The billing period advances to the next cycle

Paused subscriptions can auto-resume after a set number of billing cycles or on a specific date.

See [Pause a subscription](/guides/billing/subscription-pause) for details.

## Cancellation options

Subscriptions support several cancellation strategies:

* **Cancel immediately** with optional refund (full, prorated, or none)
* **Cancel at period end** to let the customer use the service through the paid period
* **Cancel on a specific date** for scheduled termination

See [Cancel a subscription](/guides/billing/subscription-cancel) for details.

## Fixed-term subscriptions

Set `total_billing_cycles` to create a subscription with a fixed term. The lifecycle engine tracks remaining cycles and stops billing when all cycles complete.

# Webhook events

PaymentKit emits events at each state transition. Use these to trigger business logic in your application.

| Event                         | Trigger                              |
| ----------------------------- | ------------------------------------ |
| `subscription.created`        | Subscription created                 |
| `subscription.updated`        | Subscription state or fields changed |
| `subscription.paused`         | Subscription paused                  |
| `subscription.resumed`        | Paused subscription was resumed      |
| `subscription.cancelled`      | Subscription cancelled               |
| `subscription.trial_will_end` | Trial ends in 3 days                 |
| `invoice.paid`                | Renewal payment succeeded            |
| `invoice.payment_failed`      | Renewal payment failed               |