Understanding what happens in the natural course of a subscription helps provide the smoothest experience for both you and your users. Here you’ll read about:
The subscription lifecycle
Stripe has an associated event for every activity that happens with a subscription. (There are dozens of events that occur when using Stripe, not all of which are specific to subscriptions.)
Taking a basic example of a new customer with a valid payment method and no trial period on the subscription, the following image shows the lifecycle of the most important events that occur. (Note that the exact order in which you receive the events—particularly those that happen “immediately”—is not guaranteed.)
When certain events occur, you want to take corresponding steps on your website, such as:
- Emailing the customer when a payment fails
- Extending the length of time that a customer can use your service
- Terminating access when a subscription is canceled
As subscription events primarily occur behind the scenes—and mostly asynchronously, your site should listen for them via webhooks.
Subscription settings and payment failures
Once a subscription has been created, a failure to pay an invoice becomes the most important event that could happen. Failures occur for many reasons:
- Lack of an actual payment source on the associated customer
- Attempt to use an outdated or expired payment source
- An actual decline of an otherwise valid payment source
Your subscription settings dictate how Stripe responds when an invoice payment fails.
You can have invoice payments be retried up to three times, each 1, 3, 5, or 7 days after the previous attempt. This flexibility allows for only one payment attempt to ever be made or up to four total attempts, over as many as 21 days.
After your set number of attempts, Stripe stops attempting to pay the invoice and take the next action you dictate. The options are:
- Cancel the subscription
- Mark the subscription as unpaid
- Leave the subscription as-is
(See the next section for more information on these subscription states.)
After the final payment attempt on an invoice, no further payment attempts are made until a new payment method is added to the customer.
Note that changing your subscription settings only affect future retries. Once a payment attempt is made on an invoice, its next_payment_attempt value is set using the subscription settings as they are at that moment.
If a subscriptions charge fails, Stripe can optionally send an email to your customers prompting them to update their payment information. These are sent to the email address associated with the Customer object.
The Subscription object has a
status property that reflects the subscription’s current state. Its possible values are:
A subscription still in its trial period is trialing and moves to active once the trial period is over. This occurs before the first payment is attempted.
When an invoice payment on a subscription fails, the subscription becomes past_due. After Stripe exhausts all payment retry attempts, the subscription remains past_due or moves to a
status of either canceled or unpaid, depending upon your retry settings:
With a canceled subscription, the most recent, unpaid invoice is closed, and no further invoices are generated. A
customer.subscription.deletedevent is triggered, following the
invoice.payment_failedevents that preceded it. (You can see that a subscription was canceled automatically—as opposed to by your request—if the
requestproperty is null.) Since the subscription has been deleted, it cannot be reactivated. Instead, you can collect updated billing details from your customer, update your customer’s default payment source in Stripe, and create a new subscription for the customer.
If you choose to mark the subscription as unpaid, the most recent, unpaid invoice remains open, and no subsequent payments are attempted on any invoice. (Invoices will continue to be created, but then immediately closed.) Additionally, updating the payment source for the customer does not trigger a retry of the most recent invoice. After updating the customer’s payment source, you may choose to reopen and pay any unpaid, closed invoices. This default behavior allows you to best dictate how an unpaid subscription is billed upon reactivation.
If you choose to leave the subscription as-is (in a past_due state), the most recent, unpaid invoice remains open, new invoices are generated, and payment on those new invoices is attempted. You can use this behavior if you want to continue attempts to bill your customers every month, even when previous invoice payments have failed.
To set a subscription
status back to active from an unpaid or past_due state, open the most recent invoice and attempt to pay it. Note that paying any other invoice—that is not the most recent—does not change the subscription’s status.
Other subscription events
Other subscription events occur that you may need to handle, depending upon your use of subscriptions.
If a subscription is on a trial period, we’ll let you know the trial is ending via the
customer.subscription.trial_will_end event. This event notification goes out 3 days before the trial period concludes (unless that’s not possible, such as when a trial is only 1 day long).
Successful payments of invoices also trigger
invoice.updated events, notifying you that the invoice’s
paid attribute now has a true value. If an invoice payment fails, that also triggers
invoice.updated, this time with a
paid value of false. You also see an
invoice.payment_failed event in that case.
If the invoice payment failed because the charge is declined, that comes with a
charge.failed event as well.
Changing a subscription results in
customer.subscription.updated events. There are other relevant events you’ll encounter when using subscriptions related to:
- Invoice items
See the API reference for the complete list.
Congrats! You've learned about the subscription lifecycle at Stripe. Some documentation you might want to read next: