Lifecycle of a Subscription

Stripe has an associated event for everything that happens with a subscription. (There’s actually dozens of events that occur when using Stripe, not all of which are specific to subscriptions.)

For our example of a new customer with a valid payment method and no trial period, this image shows the lifecycle of events.

When certain events occur, you should listen for the associated webhooks and take corresponding steps on your website (e.g., extending the length of time that a customer can use your site, or terminating access when a subscription is canceled). Note that the exact order in which you receive the events is not guaranteed.

Other important events can also occur, such as invoice.payment_failed. While these aren’t part of the normal cycle, you’ll still need to be set up to handle them.

• Events API

Webhooks

Webhooks are a tool Stripe uses to notify your site of the events that occur related to your account. To use them, you’ll have to create an endpoint (e.g., a script) on your site that Stripe will send information to and register that endpoint with Stripe.

• Read more about Webhooks

Once you register a webhook endpoint, Stripe will wait up to 72 hours for that endpoint to successfully receive the notification before attempting payment on an invoice.

Stripe will always attempt to pay an invoice except in certain situations:

• If no valid payment information is stored for the customer, Stripe won’t attempt to pay the invoice.
• If previous attempts have failed (and the account has been marked as unpaid), Stripe will continue to generate invoices but will not attempt to pay them.
• If you’re using webhooks and Stripe does not see a successful response for the invoice.created event, Stripe will continue retrying the webhook every hour for up to 72 hours. During that time, no payment will be attempted until a successful response is received.

If the webhook hasn’t succeeded after 72 hours, Stripe will attempt to pay the invoice. Along the way, you’ll also get an email notifying you that the webhook is failing.

As new ideas are introduced in the rest of the guide, the corresponding events will be mentioned. It’s up to your webhooks to recognize these events and react accordingly. For example, you’ll want to mark a customer as inactive in your database when the customer.subscription.deleted event occurs.

Payment failures

A subscription also changes if an invoice is generated but the charge attempt fails. The events that occur and the results of those events when a charge attempt fails depend upon your subscription account settings.

In the Stripe dashboard, under Account Settings > Subscriptions, you can choose how Stripe should respond when an invoice payment attempt fails. Stripe can retry failed payments up to four times, and you can specify the delay between attempts.

You can also decide whether the subscription’s status should be marked as unpaid or canceled after the last payment attempt fails. (Note that a payment failure on the very first invoice of a subscription without a trial results in the customer never being subscribed to the plan.)

In either case, after the final payment attempt on an invoice, no further payment attempts will be made until a new payment method (i.e., credit card) is added to the customer’s account. The two states differ in what happens from that point forward.

• With a canceled subscription, the unpaid invoice will be closed, and no further invoices will be generated. A customer.subscription.deleted event is triggered, following the charge.failed and invoice.payment_failed events that would have preceded it. Since the subscription is fully deleted at this point, there is no direct way to “reactivate” it. If you collect updated billing details from your customer, you can “start from scratch”: update your customer’s default card and add the customer to a new subscription.

• If you choose to mark the subscription as unpaid, it will continue to generate new invoices, but those invoices will be marked as closed. This prevents subsequent payment attempts, which would fail.

• If you choose to leave the subscription as-is, it will continue to generate new invoices, and those new invoices will be attempted. You can use this if you want to keep attempting to bill your customers every month, even when previous invoice payments have failed.

Note that when a subscription has been scheduled for cancellation using at_period_end, it can be reactivated at any point up to the end of the period with any update via the API or the dashboard.

TIP: When an invoice payment fails, the customer gets flagged as “delinquent”, letting you easily identify delinquent customers using filters in the dashboard. The delinquent property always represents whether the most recent payment attempt succeeded or failed. When that invoice is paid, the delinquent label is removed.

A subscription will be reactivated when the most recently created unpaid invoice for the subscription is paid. So, if it is June 15th, but the May 1st and June 1st invoices are both unpaid:

• Successfully paying the May 1st invoice will not reactivate the subscription.
• Successfully paying the June 1st invoice will reactivate the subscription.