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.statusis set to
invoice.statusis set to
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:
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
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
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
To reactivate the subscription, you need to:
Collect new payment information
Turn automatic collection back on by setting auto advance to
trueon 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
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
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
uncollectiblestate, the subscription state is set to
If the collection_method is set to
charge_automaticallyon the invoice, and Stripe stopped dunning on the invoice because of retry limits, the subscription state is set to
past_duebased 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
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
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.