Subscription States

The state of a subscription is reported in the state attribute of a subscription. The valid states are:

  • trialing
  • trial_ended
  • active
  • soft_failure
  • past_due
  • canceled
  • unpaid
  • expired

Additionally, the following states are reserved for internal/future use:

  • assessing
  • pending
  • suspended
  • paused

These states may be further broken down in to 3 categories: Live, Problem, and End of Life.

You should plan on delivering services for any state except an End of Life state.

Live States

trialing

A subscription in trialing state has a valid trial subscription. This type of subscription may transition to active once payment is received when the trial has ended. Otherwise, it may go to a Problem or End of Life state.

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.

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.

paused

Indicates that your account with Chargify is in arrears.

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 :)

Problem States

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.

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.

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, Chargify 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 an 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 Chargify 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 expired subscription then, is one that stayed active until it fulfilled its full period.

suspended

Reserved and currently unused. May be used in the future for subscriptions that may be restarted (i.e. after being suspended due to non-payment, then payment resumes)

trial_ended

A subscription in a trial_ended state is a subscription which 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.

Troubleshooting

If you find a subscription that remains in the pending or assessing state, please open a support ticket and let us know.

State Transitions

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.

Past Due to Trialing

Scenario: A subscription completes its trial period and then becomes Past Due because 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.