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, 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 /v1/invoices/:id/pay 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. In cases where this initial payment fails, the subscription’s status will be incomplete.

    In order to make the subscription move from incomplete to active, you will need to get your customer to 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 will automatically move the subscription to an incomplete_expired status. The rationale for this shorter window is that this first subscription occurs generally 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 invoice will require your intervention to complete payment and to progress the subscription to an active status. You will need to first add an alternative payment source. Next, retry payment, using the /v1/invoices/:id/pay endpoint (and referencing the latest subscription invoice).

    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.

    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.) Additionally, updating the payment method for the customer does not trigger a retry of the draft invoices. You may choose to then 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 invoice is a billing=charge_automatically type invoice and we’ve stopped dunning on an invoice due to hitting the retry limit, we will transition the subscription state to canceled , unpaid or past_due, based on your Billing Settings
    • If the invoice is a billing=send_invoice type invoice and is past its due date, set the subscription state 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), there will never be a previous invoice and we 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 three 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.

    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:

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode

    Was this page helpful? Yes No

    Send

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