Subscription Life Cycle

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:

1. Subscription is created

2. An invoice is created for the subscription and then paid

3. subscription.status is set to active and invoice.status is set to paid

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 is incomplete

• invoice.status is open

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 or uncollectible state, the subscription state is set to active.

• 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 to canceled , unpaid, or past_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 to past_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: