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

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 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 (from the resume date to period end)
• Payment is attempted on the prorated invoice (failure triggers standard dunning, but does not block resumption)
• 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. If neither option is configured, the subscription remains paused indefinitely until manually resumed.

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