Billing Lifecycle and Events

    Learn more about the lifecycles of subscriptions and invoices to better understand how billing works on Stripe.

    Understanding what happens in the natural course of a billing relationship 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 or invoice. The exact events sent depend on the type of subscription. A subscription paid automatically via credit, for example, has different events than a subscription paid manually by sending an invoice to the customer every billing cycle. Other options, such as creating subscriptions with trials, also affect the events sent. Check the events documentation for a comprehensive list of all events Stripe can send.

    Some events are sent immediately when a subscription is created, while others recur on regular billing intervals. Creating a customer with a valid payment method and subscribing them to a plan with automatic payment causes Stripe to send the following events—though the exact order is not guaranteed:

    1. A customer.created event is sent, indicating a customer record was successfully created.
    2. A customer.subscription.created event is sent, indicating that the customer was successfully subscribed to the specified plan.
    3. An invoice.created event is sent, indicating that an invoice was issued for the first billing period.
    4. A charge.succeeded event is sent, indicating that the customer’s payment method was successfully charged.
    5. An invoice.payment_succeeded event is sent, indicating that the invoice was successfully marked paid.

    Going forward, a cycle of events repeats every billing period:

    1. When the subscription approaches its renewal date, an invoice.upcoming event is sent.
    2. When the subscription period elapses, an invoice.created event is sent.
    3. About an hour after the invoice is created, it is frozen and a charge is attempted. A charge.succeeded event is sent to indicate that the payment was successful.
    4. An invoice.payment_succeeded event is sent to indicate that the invoice was marked paid.

    You may want to take specific actions in response to certain events, 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 asynchronously and behind the scenes, your integration should listen for them via webhooks.

    The invoice lifecycle

    Automatic lifecycle

    Automatically-paid invoices have the following lifecycle:

    1. The invoice is created and an invoice.created event is sent.
    2. About an hour after creation, Stripe automatically attempts to pay it using the default payment method.
    3. If the payment is successful, an invoice.payment_succeeded event is sent and the invoice’s paid state is set to true.
    4. If the payment fails or the customer does not have a valid payment source, an invoice.payment_failed event is sent and the subscription becomes past_due.

    In this flow, Stripe never notifies the billed customer billed about the invoice. An automatic payment is attempted on the invoice made shortly after it is generated. The customer, however, receives an email receipt if you have that enabled.

    Emailed invoice lifecycle

    Manually-paid invoices have a slightly different lifecycle:

    1. The invoice is created with a set due date and an invoice.created event is sent.
    2. About an hour after creation, Stripe sends the invoice to the customer via email and sends an invoice.sent event.
    3. At some later point, the customer pays the invoice by sending an ACH credit transfer. An invoice.payment_succeeded event is sent and the invoice’s paid state is set to true.
    4. If the customer does not pay the invoice before the due date or sends an amount which is not automatically reconciled, the subscription becomes past_due.

    Invoices are still editable for a period of time after they are created. Invoices that are paid automatically are still editable between creation and the first automatic payment attempt. Invoices that are paid manually are still editable between creation and when they are emailed to the user. When an invoice is no longer editable, you cannot add invoice items to it or make other modifications that affect the amount due. You can, however, still add invoice items to the customer—new items will apply to the next invoice.

    Subscription states

    The Subscription object has a status property that reflects the subscription’s current state. Its possible values are:

    • trialing
    • active
    • past_due
    • canceled
    • unpaid

    trialing

    A subscription in an active trial has a status of trialing.

    active

    A subscription created without a trial has a status of active. Subscriptions which reach the end of their trial periods transition to the active state.

    For automatically-paid subscriptions, becoming active triggers the first payment attempt on the subscription. The behavior of a failed first payment differs depending on whether a subscription was created with a trial:

    • A failed first payment on an automatically-paid subscription without a trial will blocks the subscription from being created.
    • A failed first payment on an automatically-paid subscription with a trial starts Stripe’s payment recovery process, even if the trial was as short as one second long. The subscription is always created.

    For subscriptions paid manually, moving to the active state triggers an invoice to be sent to the customer.

    past_due, canceled, and unpaid

    When an automatic payment on a subscription fails, a charge.failed event and an invoice.payment_failed event are sent and the subscription state becomes past_due. Stripe attempts to recover payment according to your configured retry rules.

    When an invoice for a subscription paid manually is not paid on time, the subscription state becomes past_due. Stripe may attempt to email reminders to the customer according to your configured settings.

    See the subscription settings section of this page for more information about configuring Stripe’s recovery process.

    After Stripe completes the configured recovery process, the subscription status remains past_due or transitions to either canceled or unpaid, depending upon your settings:

    • When a subscription becomes canceled, the most recent unpaid invoice is closed and no further invoices are generated. A customer.subscription.deleted event is triggered. (You can see that a subscription was canceled automatically—as opposed to by your request—if the customer.subscription.deleted event’s request property is null.) Since the subscription has been deleted, it cannot be reactivated. Instead, collect updated billing details from your customer, update their default payment source in Stripe, and create a new subscription for their customer record.

    • 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 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 the past_due state), the most recent unpaid invoice remains open, new invoices are generated, and payment on those new invoices is attempted. 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.

    Invoice states

    Invoices have meaningful properties that reflect the invoice’s status:

    • attempt_count
    • attempted
    • closed
    • forgiven
    • next_payment_attempt
    • paid

    The values of these attributes differ for the first invoice on a new subscription, subsequent invoices, and for invoices with payment failures.

    The first invoice on an automatically-paid subscription is effectively closed from the moment it’s created. If the payment succeeds or no payment is required, the invoice is also marked as paid and the subscription is created. If the payment fails, the subscription attempt fails, too, and no invoice or subscription exists. Any API call that results in a new or modified subscription, such as upgrading or downgrading the plan, also creates a new invoice that is closed from the onset.

    When a subscription is billed automatically instead of via the API, the invoice behavior is a bit different. You receive an invoice.created event when the invoice is created. This time, the invoice’s closed attribute is false, which means it’s open for modification via invoice items.

    When payment on an automatically-paid invoice fails, the attempt_count is incremented and the next_payment_attempt value is set according to your retry settings.

    Closing and forgiving invoices

    You can change an invoice’s state by manually marking it as closed or by closing and forgiving it. Subsequent payment attempts are never made on closed or forgiven invoices. Forgiving an invoice instructs Stripe to update the subscription status as if the invoice was successfully paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened.

    Subscription settings and recovery

    Your subscription settings dictate how Stripe responds when an invoice payment fails or becomes past due. The settings for automatic payment and manual payment are configured independently.

    Automatic payment

    Once a subscription with an automatic payment method has been created, a failure when attempting 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

    You may configure Stripe to retry failed automatic payments. Smart Retries utilize Stripe’s machine learning to pick the optimal time to retry over a configurable period of time up to one month after the initial payment fails.

    If you prefer to control the retry schedule precisely, you may select custom dunning rules. This setting allows configuring up to three retries, each occurring 1, 3, 5, or 7 days after the previous attempt. This flexibility allows for precise control of up to four total attempts, over as many as 21 days.

    When Stripe finishes attempting to recover failed payment on an automatically paid invoice, the subscription transitions according to your settings. The options are:

    • Cancel the subscription
    • Mark the subscription as unpaid
    • Leave the subscription as-is

    (See the subscription states section of this page for more information on these choices.)

    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 affects 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.

    Manual payment

    Invoices which are sent to be paid manually are due a configurable number of days after being sent. Stripe can be configured to send up to three reminders to the customer from 10 days before the due date up to 60 days after the invoice is due.

    You may configure Stripe to take additional action on the subscription 30, 60, or 90 days after an invoice becomes past due. The options are:

    • Cancel the subscription
    • Mark the subscription as unpaid
    • Leave the subscription as-is

    (See the subscription states section of this page for more information on these choices.)

    Other events

    Other events occur that you may need to handle, depending upon your use of subscriptions and invoices.

    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:

    • Coupons
    • Discounts
    • Invoice items
    • Plans

    See the API reference for the complete list.

    Next steps

    Congrats! You’ve learned about the subscription lifecycle at Stripe. Some documentation you might want to read next: