> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/guides/billing/subscriptions/subscription-lifecycle/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Subscription lifecycle

# 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 configured at creation                                   |
| 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   | Past due  | Trial ends and first payment fails                                    |
| 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. Waits for a finalization delay (configurable, allows invoice preview)
3. Finalizes the invoice (DRAFT to OPEN) and attempts payment collection
4. On success: advances the billing period, then re-evaluates for 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 `customer.subscription.trial_will_end` event fires
3. At trial end:
   * A renewal invoice is generated for the first paid billing period
   * Payment is collected automatically
   * On successful payment, the subscription transitions to **Active**

> **Tip**
>
> Listen for the `customer.subscription.trial_will_end` webhook event to notify customers before their trial expires. This gives them time to add a payment method or cancel before being charged.

## Payment failure and dunning

When a payment fails on an active subscription:

1. The subscription moves to **Past due** (after the invoice's period end)
2. PaymentKit retries payment on a smart schedule based on billing cycle:
   * **Standard cycles (7+ days):** 1-hour immediate retry, then every 4 days
   * **Short cycles (2-6 days):** 2-day intervals
   * **Daily cycles:** 23-hour intervals
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 + mark uncollectible** (default): Cancel subscription and mark invoices uncollectible
   * **Cancel + leave open:** Cancel subscription but leave invoices open for manual collection
   * **Past due + mark uncollectible:** Keep subscription in past due state and mark invoices uncollectible
   * **Past due + leave open:** Keep subscription in past due state and leave invoices open

See [Automatic retries & emails](/guides/billing/dunning-recovery/automatic-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. Billing dates (`current_period_end`, `next_invoice_date`) remain frozen at their pre-pause values.

**Auto-resume**: Paused subscriptions can automatically resume after a set number of billing cycles (`pause_for_cycles`) or on a specific date (`resumption_date`). If neither is configured, the subscription remains paused until manually resumed.

**Resume billing behavior**: When a subscription resumes, the billing timeline is recalculated based on the account's `resume_billing_behavior` setting:

* **`reset_anchor`** (default): Re-anchors billing to the resume date. The customer is charged a full period from the resume date — no catch-up for time paused.
* **`catch_up`**: Preserves the original billing anchor and generates catch-up invoices for each billing cycle elapsed during the pause.

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

## Cancellation options

Subscriptions support three cancellation timing strategies:

* **Cancel immediately** (default) - Terminates the subscription right away
* **Cancel at period end** - Schedules cancellation for the end of the current billing period, letting the customer continue using the service through the paid period
* **Cancel on a specific date** - Schedules cancellation for a specific future datetime

When canceling immediately, you can specify a refund option:

* **none** (default) - No refund issued; any open invoices are voided
* **full** - Refunds the full paid amount for the current billing period
* **prorated** - Refunds the unused portion of the current period based on seconds remaining
* **cancel\_unpaid** - Voids all open/draft invoices without issuing refunds

Use **preview mode** (`is_preview: true`) to calculate the refund amount without executing the cancellation.

You can also capture **cancellation details** including a customer comment, structured feedback category (e.g., `too_expensive`, `missing_features`), and a reason code.

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

## Fixed-term subscriptions

Set `total_billing_cycles` to create a subscription with a fixed term. The lifecycle engine tracks `remaining_billing_cycles` and decrements it after each successful renewal. When all cycles complete:

* If `contract_auto_renew` is `true`: The contract renews automatically, resetting `remaining_billing_cycles` to `total_billing_cycles`
* If `contract_auto_renew` is `false` (default): Billing stops and the subscription ends

# Webhook events

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

| Event                                   | Trigger                                   |
| --------------------------------------- | ----------------------------------------- |
| `customer.subscription.created`         | Subscription created                      |
| `customer.subscription.updated`         | Subscription state or fields changed      |
| `customer.subscription.paused`          | Subscription paused                       |
| `customer.subscription.pause_scheduled` | Pause scheduled for end of billing period |
| `customer.subscription.resumed`         | Paused subscription was resumed           |
| `customer.subscription.cancelled`       | Subscription cancelled                    |
| `customer.subscription.trial_will_end`  | Trial ends in 3 days                      |
| `invoice.paid`                          | Renewal payment succeeded                 |
| `invoice.payment_failed`                | Renewal payment failed                    |

> Understand how subscriptions move through states from creation to cancellation, and how payment outcomes drive automatic transitions.