Subscription states

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

Key transitions

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

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 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 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 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.