The state of a subscription is reported in the
state attribute of a subscription. The valid states are:
- Active (
- Canceled (
- Expired (
- On Hold (
- Past Due (
- Soft Failure (
- Trialing (
- Trial Ended (
- Unpaid (
- Suspended (
- Awaiting Signup (
Additionally, the following states are reserved for internal/future use:
- Assessing (
- Failed to create (
- These states may be further broken down into 3 categories:
- End of Life
- Paused (
- Pending (
You should plan on delivering services for any state except an End of Life state.
Lifecycle of a Subscription
From the time when a subscription is created on your site, to the time that it is canceled, the subscription can take on many other statuses in Advanced Billing. It’s important to understand that when a subscription is in a particular state, there are some situations where it cannot transition directly to the desired state.
- An expired subscription must be canceled before it can be reactivated.
- An unpaid subscription can transition to the active state only after being canceled beforehand.
The graphic above details all of the paths that a subscription takes. It’s important to note that the arrows indicate the path that the subscription can take. In certain situations, you can only travel in one direction between states.
- Expired to Canceled
- Trialing to Trial Ended
- Active to Expired
Please see the section below on state transitions to understand how to move subscriptions between states.
active: A normal, active subscription. It is not in a trial and is paid and up to date. This is where you want all your Customers to be :)
assessing: An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed.
paused: Indicates that your account with Advanced Billing is in arrears.
pending: An internal (transient) state that indicates a subscription is in the creation process. Do not base any access decisions in your app on this state, as it may not always be exposed.
trialing: A subscription in
trialingstate has a valid trial subscription. This type of subscription may transition to
activeonce payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state.
past_due: Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers.
soft_failure: Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action when needed.
unpaid: Indicates an unpaid subscription. A subscription is marked unpaid if the retry period expires and you have configured your Dunning settings to have a Final Action of “mark the subscription unpaid”.
While a subscription is marked as unpaid, its period still advances and new charges continue to accrue. However, Advanced Billing does not attempt to automatically collect any overdue balance. Collecting the balance, or eliminating the balance through an Adjustment is your responsibility.
End of Life States
canceled: Indicates a canceled subscription. This may happen at your request (via the API or the web interface) or due to the expiration of the Dunning process without payment. See the Reactivation documentation for info on how to restart a canceled subscription.
While a subscription is canceled, its period will not advance, it will not accrue any new charges, and Advanced Billing will not attempt to collect the overdue balance.
expired: Indicates a subscription that has expired due to running its normal life cycle. Some products may be configured to have an expiration period. An
expiredsubscription then is one that stayed
activeuntil it fulfilled its full period.
failed_to_create: Indicates that signup has failed. (You may see this state in a
on_hold: Indicates that a subscription’s billing has been temporarily stopped. While it is expected that the subscription will resume and return to
activestatus, this is still treated as an “End of Life” state because the customer is not paying for services during this time.
suspended: Indicates that a prepaid subscription has used up all their prepayment balance. If a prepayment is applied, it will return to an active state.
trial_ended: A subscription in a trial_ended state is a subscription that completed a no-obligation trial and did not have a card on file at the expiration of the trial period. See Product Pricing – No Obligation Trials for more details.
Action Options During Various States
As you inspect the Actions drop-down menu in the Subscription Summary, you will find that the options available will change based on the current Subscription state.
Please see our documentation on Subscription State Actions for a full overview of what Actions are available based on the state of the Subscription.
If you find a subscription that remains in the
assessing state, please open a support ticket and let us know.
Subscriptions normally transition automatically between the states in response to events such as signups, trials, payments, and expirations.
Occasionally, manual intervention is necessary to move a subscription into the desired state. Please see the examples below to understand the process necessary to move subscriptions through the existing state to the desired state.
Expired to Active
Scenario: A subscription has expired. You would like to reactivate the subscription. However, the subscription must be canceled first. Once the subscription has been canceled, you may now reactivate the subscription.
Past Due to Trialing
Scenario: A subscription completes its trial period and then becomes Past Due because the payment was expected at the end of the trial, but the charge was declined or there was no card on file. The customer requests more time to try out your product, and you want to clear the balance and extend the trial.
Since the trial has already ended, simply resetting the balance of a Past Due subscription will put it into the Active state.
In order to return it to the Trialing state, you must first cancel the subscription using the Cancel Immediately option, and then reactivate it, at which time you will have the option to include the trial. (The balance will be reset to zero by default, however, you have the option to NOT reset it.)
If needed, you can now change the next billing date, and the trial end date will automatically be adjusted to match.
Trial Ended to Active
Scenario: A subscription completes its trial, the trial ends, and the subscription obtains the status of trial ended. In order to resurrect this subscription, you may reactivate it. This will result in the subscription having the active status.
Unpaid to Active
Scenario: A subscription completes the dunning process and arrives in the Unpaid state. You, as the merchant, wish to reactivate the subscription. There are a couple of options available.
Click “Retry/Reactivate” on the subscription’s Summary page. This will attempt to collect the balance on the subscription via the active credit card on file. If the payment is unsuccessful, the subscription will remain unpaid.
Click “Reset to $0” on the subscription’s Summary page. This effectively forgives the subscription’s balance.
The end result of either option, presuming that the payment from option 1 is successful, will be a subscription in an active state.
Suspended to Active
Scenario: A prepaid subscription is not configured to auto-replenish. The customer records 50 units of usage, which takes their prepayment account balance into the negative. They are now suspended.
You may either collect a prepayment from the prepayments tab or visit the reactivation page, which will prompt you to add a prepayment. Note that the prepayment amount must exceed any negative balance caused by over usage.