Billing Lifecycle and Events

    Learn more about the lifecycles of Stripe Billing’s subscriptions and invoices.

    Understanding what happens in the natural course of a billing relationship helps provide the smoothest experience for you as well as your users. Here, you’ll read about:

    The subscription lifecycle

    Stripe has an event associated with 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 that a customer record was successfully created.
    2. A customer.subscription.created event is sent, indicating the subscription has been created.
    3. An invoice is drafted and then finalized, prior to a charge attempt being made. The invoice.created and invoice.finalized events are sent, indicating that this 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.

    After this first invoice, the following 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, indicating the creation of a draft invoice.
    3. About an hour after the invoice is created, it is finalized (changes are no longer permitted), and an invoice.finalized event is sent. A charge is attempted, and 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 might 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

    Automatically paid invoices, and emailed invoices, each have their own lifecycle.

    Automatic invoice lifecycle

    Automatically paid invoices have the following lifecycle:

    1. A status=draft invoice is created and an invoice.created event is sent.
    2. About an hour after creation, the invoice is finalized (changes are no longer permitted) and an invoice.finalized event is sent. The status of the invoice is open and 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 status field will show up as paid.
    4. If the payment fails or the customer does not have a valid payment method, an invoice.payment_failed event is sent, the subscription becomes past_due if the subscription’s status is not incomplete, and the invoice’s status field remains open.

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

    Emailed invoice lifecycle

    Manually paid invoices have a slightly different lifecycle:

    1. A status=draft invoice is created with a set due date, and an invoice.created event is sent.
    2. About an hour after creation, the invoice is finalized (changes are no longer permitted), and an invoice.finalized event is sent. The status of the invoice is open. 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 status field will show up as paid.
    4. If the customer does not pay the invoice before the due date, or sends an amount that is not automatically reconciled, the subscription becomes past_due, a customer.subscription.updated event is sent, and the status field remains open.

    Invoice editability

    Invoices are still editable for some time after they are created:

    • Invoices that are paid automatically remain editable between their creation and the first automatic payment attempt, at which point they are finalized.
    • Invoices that are paid manually are still editable between creation and when they are finalized and emailed to the user.

    When an invoice is finalized, you cannot add invoice items to it, nor make other modifications that affect the amount due. You can, however, still add invoice items to the customer—the 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
    • incomplete
    • incomplete_expired
    • past_due
    • canceled
    • unpaid

    trialing

    A subscription in a current trial has a status of trialing.

    active

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

    For automatically paid subscriptions, the subscription is always created for valid requests even if the first payment fails. Payment recovery behavior differs depending on whether or not the subscription was created with a trial:

    • On an automatically paid subscription without a trial, a failed first payment results in a subscription in the incomplete status, without Stripe’s payment recovery process. To complete payment on the subscription invoice you will need to reattempt payment with a different Source using the Pay Invoice endpoint.
    • On an automatically paid subscription with a trial, a failed first payment starts Stripe’s payment recovery process, putting the subscription into a past_due status.

    incomplete and incomplete_expired

    When a subscription is created, the first payment attempt occurs synchronously. If the initial payment doesn’t succeed, the subscription’s status will be incomplete. If you’re using Checkout to create subscriptions, it may create incomplete subscriptions that transition to active on initial payment.

    To transition a subscription from incomplete to active, your customer must complete a successful payment. Stripe expects an incomplete subscription to be resolved within a 23-hour expiration window. If the 23-hour window passes without resolving the incomplete status, Stripe automatically transitions the subscription to an incomplete_expired status. The reason behind this shorter window is that this first subscription generally occurs when the customer is on session (either in front of their browser or mobile device) attempting to pay. We recommend creating a new subscription if there is a significant delay between first and second attempts to checkout.

    Subscription expiration workflow

    Any incomplete subscription will require your intervention to complete payment and progress to an active status. The reason for payment failure can be found on the subscription.latest_invoice.payment_intent as described here.

    Effects of subscription expiry

    If the 23-hour period elapses, the subscription will be set to an incomplete_expired status. This has the side effect of voiding the associated invoice.

    Such expired subscriptions are not active, and will not bill the customer. This status exists for bookkeeping purposes, to keep track of customers who have failed to fully activate their subscription billing.

    Updates to incomplete and incomplete_expired subscriptions

    • incomplete subscriptions can only have their metadata and default_source be updated. This is so that we can ensure the generated invoice stays in sync. If you need to make substantial modifications to a subscription in this status, consider creating a new one and letting the incomplete subscription expire.
    • incomplete_expired subscriptions cannot be updated. This is a terminal state for a subscription.

    Controlling incomplete subscription behavior

    The incomplete and incomplete_expired status was introduced in the 2019-03-14 API version. Prior to that version, subscription creation attempts that resulted in a payment failure or that required additional customer action would return an API error without creating a subscription. If you’re using an older API version, you can still use the new behavior by passing the payment_behavior=allow_incomplete flag on all API calls that create and update subscriptions as described here:

    API Version Payment behavior Payment failure result
    2019-03-14 or newer [Default] allow_incomplete incomplete
    2019-03-14 or newer error_if_incomplete No subscription created
    Before 2019-03-14 allow_incomplete incomplete
    Before 2019-03-14 [Default] error_if_incomplete No subscription created

    Below is a list of endpoints the payment_behavior flag can apply to:

    For creating and updating customers, the payment_behavior flag is only supported when subscribing a customer to a plan in the API request. Creating and updating subscriptions using the Customer object is no longer documented, but the APIs are still supported for legacy reasons.

    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 manually-paid subscription is not paid on time, the subscription state becomes past_due. Stripe can attempt to email reminders to the customer, according to your configured settings.

    For more information about configuring Stripe’s recovery process, see Subscription settings.

    After Stripe completes the configured recovery process, the subscription status either remains past_due, or transitions to one of 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 method 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 and will remain as drafts with automatic collection turned off. auto_advance is set to false).) Additionally, updating the payment method for the customer does not trigger a retry of the draft invoices. You may choose to turn automatic collection back on, finalize and send/pay any draft invoices afterwards. 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.

    Resetting to active

    To set a subscription status from an unpaid or past_due state back to active, open the most recent invoice and attempt to pay it. Note that paying any other invoice—one that is not the most recent invoice—does not change the subscription’s status.

    Voiding a subscription created invoice

    If you are voiding the most recent invoice for a subscription, Billing steps through the subscription’s invoices, most recent to oldest, evaluating these conditions until one matches:

    • If the invoice is in a paid or uncollectible state, we’ll set the subscription state 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, we will re-evaluate these conditions on the next most recent invoice, continuing until all invoices have been evaluated.

    If no invoices match any of the above criteria, the subscription state is set to active.

    In the case of an incomplete subscription (where a payment attempt has never been completed) voiding the first invoice of the subscription will set the subscription state to expired, reflecting that the subscription has not activated.

    Invoice states and properties

    The Invoice has its own status property that reflects the invoice’s current state. Its possible values are:

    • draft
    • open
    • paid
    • void
    • uncollectible

    The status changes as an invoice progresses through its lifecycle. For details, see Invoicing Workflow.

    Additionally, invoices have meaningful properties that reflect the invoice’s payment status:

    • attempt_count
    • attempted
    • next_payment_attempt

    These properties’ values differ for the first invoice on a new subscription, versus subsequent invoices, versus invoices with payment failures.

    The first invoice on an automatically paid subscription is effectively finalized from the moment it’s created. If the payment succeeds, or if no payment is required, the invoice is also set to status=paid, and the subscription is created.

    If the payment fails, the subscription is created in incomplete and the invoice is immediately closed. 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 outset.

    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.

    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 method on the associated customer
    • Attempt to use an outdated or expired payment method
    • An actual decline of an otherwise valid payment method

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

    If you prefer to control the retry schedule precisely, you can select custom retry rules. This setting allows configuring up to three retries, each a specific number of days after the previous attempt. This flexibility allows for precise control of up to four total attempts, over many 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

    For more information on these choices, see 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 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.

    Emails

    Stripe can optionally send different emails to customers, using the email addresses associated with the Customer object:

    • An upcoming renewal reminder at the same time that the invoice.upcoming event is sent.
    • A failed payment notification prompting them to update their payment information.
    • An expiring card notification when one of your customers’ cards is due to expire.

    You can customize the URL to update a card as well as the logo and colors used in the email, as outlined here.

    Manual payment

    Invoices set for manual payment 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 invoices due date up to 60 days after the due date.

    You can 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

    For more information on these choices, see Subscription states.

    Payments requiring 3D Secure

    For both Automatic payment and Manual payment invoices, payments can sometimes require 3D Secure. When this happens, Stripe can be configured to send a confirmation email to the customer at the same time as the invoice.payment_action_required event is sent. You can also configure sending up to three reminders, from from one to seven days after the payment was intiated.

    If a payment is still incomplete after a configurable number of days, Stripe can take additional action on the subscription. The options are:

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

    Other events

    You might need to handle certain other events, depending upon your use of subscriptions and invoices.

    Trial periods

    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 three days before the trial period concludes (unless that’s not possible, such as when a trial is only one day long).

    invoice.updated

    Successful payments of invoices also trigger invoice.updated events, notifying you that the invoice’s paid attribute now has a true value and that its status is paid. If an invoice payment fails, this also triggers invoice.updated—this time, with a paid value of false, and with the status remaining open. In this case, you also see an invoice.payment_failed event.

    If the invoice payment failed because the charge is declined, that comes with a charge.failed event as well.

    Subscription changes and details

    Changing a subscription results in customer.subscription.updated events. When using subscriptions, you’ll encounter other relevant events related to:

    • Coupons
    • Discounts
    • Invoice items
    • Plans

    See the API reference for the complete list.

    Next steps

    Congratulations! You’ve learned about the subscription lifecycle at Stripe. Next, you might want to read about:

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page