Using Memberstack 2.0? There is an updated version of this article here.
Subscription statuses and definitions.
Note: the below is taken directly from Stripe.
The subscription lifecycle
A successful subscription flow looks like this:
-
Subscription is created
-
An invoice is created for the subscription and then paid
-
subscription.status
is set toactive
andinvoice.status
is set topaid
At this point, it’s safe to provision your product for your customer. Subscriptions that start with a trial have the trialing
status and then move to active
once the trial is over.
If payment fails, the subscription and invoice are still created but they have different statuses:
-
subscription.status
isincomplete
-
invoice.status
isopen
When the initial payment fails, customers have about 23 hours to make a successful payment. If payment is made, the subscription is updated to active
and the invoice is paid
.
If no payment is made, the subscription is updated to incomplete_expired
and the invoice becomes void
. This window exists because the first payment for a subscription is usually made with the customer on-session. If the customer returns to your application after 23 hours, create a new subscription for them.
The subscription’s status remains active
as long as automatic payments succeed. If automatic payment fails, the subscription is updated to past_due
and Stripe attempts to recover payment based on your retry rules.
If payment recovery fails, you can set the subscription status to canceled
, unpaid
, or you can leave it active.
For unpaid subscriptions, the latest invoice remains open but payments aren’t attempted. Invoices continue to be generated each billing cycle and remain in draft
state.
To reactivate the subscription, you need to:
-
Collect new payment information
-
Turn automatic collection back on by setting auto advance to
true
on draft invoices -
Finalize and then pay the draft invoices (make sure to pay the most recent invoice before its due date to update the subscription’s status to
active
)
Setting past_due
subscriptions to unpaid
is the default behavior because it gives you the most options for reactivating subscriptions.
Canceling subscriptions disables creating new invoices for the subscription, and stops automatic collection of all invoices from the subscription by setting auto_advance
to false
. It also deletes the subscription. If your customer wants to resubscribe, you need to collect new payment information from them and create a new subscription.
If you leave the subscription in place, the most recent unpaid invoice remains open, new invoices are generated, and payments on new invoices are attempted. Use this behavior if you want to continue attempts to bill your customers every month, even when previous invoice payments have failed.
Voiding an invoice generated by a subscription
If the subscription is incomplete
and you void the first invoice that’s generated, the subscription is updated to expired
. If you void the most recent invoice for an active subscription and it’s not the first one, the following logic is applied to each invoice (from most recent to oldest) until one of the conditions is met:
-
If the invoice is in a
paid
oruncollectible
state, the subscription state is set toactive
. -
If the collection_method is set to
charge_automatically
on the invoice, and Stripe stopped dunning on the invoice because of retry limits, the subscription state is set tocanceled
,unpaid
, orpast_due
based on your automatic collection settings. -
If the collection_method is set to
send_invoice
, and the invoice is past its due date, the state of the subscription is set topast_due
. -
If the invoice is in none of these states, the same steps are executed on the next most recent invoice.
If no invoices match any of the above criteria, the subscription state is set to active
Subscription statuses:
STATUS |
DESCRIPTION |
|
The subscription is currently in a trial period and it’s safe to provision your product for your customer. The subscription transitions automatically to |
|
The subscription is in good standing and the most recent payment was successful. It's safe to provision your product for your customer. |
|
Payment failed when the subscription was created. A successful payment needs to be made within 23 hours to activate the subscription. See the payments section for details on resolving subscriptions with this status. |
|
The initial payment on the subscription failed and no successful payment was made within 23 hours of creating the subscription. These subscriptions do not bill customers. This status exists so you can track customers that failed to activate their subscriptions. |
|
Payment on the latest invoice either failed or wasn't attempted. |
|
The subscription has been canceled. During cancellation, automatic collection for all unpaid invoices is disabled ( |
|
The latest invoice hasn't been paid but the subscription remains in place. The latest invoice remains open and invoices continue to be generated but payments aren't attempted. |
Comments
0 comments
Please sign in to leave a comment.