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 that the customer was successfully subscribed to the specified plan.
    3. An invoice is drafted and then finalized, prior to a charge attempt being made. The invoice.created and invoice.finalized events are is 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 source, an invoice.payment_failed event is sent, the subscription becomes past_due and the 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
    • 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 that 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 or not a subscription was created with a trial:

    • On an automatically paid subscription without a trial, a failed first payment blocks the subscription from being created.
    • On an automatically paid subscription with a trial, a failed first payment 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 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 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 are 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.

    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.

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

    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.

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