Subscription States Guide
What are subscription states?
Subscription states indicate exactly where a subscription is in its lifecycle. Think of them as status updates that help understand what's happening with the subscription.
API Documentation
All states and more detailed and technical information can be found in the API documentation.
The Main States
🟡 PENDING
The subscription has been created and is waiting to be activated.
What this means:
The subscription offer is ready but not yet active
Pending invoices may be visible that will be processed when activated
No services are active yet
Often set up by the Merchant before the customer submits further relevant information such as Payment method.
🟢 ACTIVE
The subscription is active and eligible for automatic renewal and on-demand invoicing.
What this means:
Access to all subscription services is available
Automatic renewals are enabled
Billing happens according to the plan
🆓 TRIAL
The subscription is in an initial trial period.
❌ CANCELED
The subscription is canceled and will expire at the end of the current billing period.
This can be initiated either
when creating the subscription by setting automatic cancellation.
when subscription already active in customer by clicking on Cancel button.
🚫NON-RENEWING
A subscription may show as NON-RENEWING in the following situations:
The subscription is not in an active or pending state
No next billing period is scheduled
The subscription is cancelled and set to expire
The subscription has a defined end date that's been reached
The subscription plan has a limited number of billing cycles that have been completed
Active subscriptions have additional sub-state flags available via API:
is_cancelled,in_trial, andhas_started. For detailed information, see API documentation.
⏸️ ON HOLD
The subscription is temporarily paused.
What this means:
Services are temporarily suspended
No billing occurs during this period
Can be reactivated to resume services
When reactivated, a new billing cycle begins
🔴 EXPIRED
The subscription has ended permanently.
What this means:
All services have stopped
Cannot be renewed or reactivated
This is the final state
How states change?
FROM | TO | CAUSE |
|---|---|---|
New | 🟡 PENDING | • Created via API • Created via customer through hosted pages |
New | 🟢 ACTIVE | • Created via API • Created via merchant in Admin |
🟡 PENDING | 🟢 ACTIVE | • Created via customer through hosted pages • Created via API |
🟢 ACTIVE | ⏸️ ON HOLD | • Paused via API or Admin • Paused via dunning process if final action is putting on hold |
⏸️ ON HOLD | 🟢 ACTIVE | • Reactivated via API or Admin |
🟢 ACTIVE | 🔴 EXPIRED | • Expired via API or Admin or by customer in customer portal • Expired via dunning process if final action is expiring subscription |
Events that can occur while active
Even when the subscription stays ACTIVE, important events can occur:
EVENT | DESCRIPTION |
|---|---|
subscription_payment_method_added | A payment method has been added to the subscription for the first time |
subscription_payment_method_changes | The payment method has been changed for a subscription with an existing payment method |
subscription_trial_end | The trial period for subscription has ended |
subscription_renewal | An invoice has been made and new billing period has started for subscription |
subscription_cancelled | Subscription has been cancelled and expires at end of current billing period |
subscription_uncancelled | A previous cancellation has been withdrawn |
subscription_changed | Subscription scheduling or pricing has been changed, e.g. by changed plan or changed next period start |
For more subscription events, see API documentation.