How subscriptions work

Subscriptions let customers make recurring payments to access a product or service. When you create a subscription, Stripe automatically generates invoices, attempts payment collection, and manages the subscription status throughout its lifecycle. A subscription moves through a predictable set of states, from creation to cancellation.

Unlike one-time payments, subscriptions require storing customer and payment method information for future billing cycles. Stripe handles the payment retry logic, dunning, and status transitions.

Subscription lifecycle

Each of the following subscription lifecycle phases maps to a status change on the Subscription object. Understanding these statuses helps you know when to provision access, notify customers, and handle errors. You can use webhook events to monitor and handle transitions between statuses.

Create the subscription

Create a new subscription in the Dashboard or with the Subscriptions API. The resulting Subscription object contains the subscribed customer, product, and price, and the status reflecting the subscription’s current lifecycle state.

When you create a subscription that requires an immediate payment, Stripe also creates an Invoice and a PaymentIntent. The subscription’s initial status is incomplete, then becomes active after the customer pays the first invoice.

Default subscription payment collection and failure handling depends on the payment method. In the API, you can configure a subscription’s payment_behavior to override the default.

If you create a trial period to delay the first charge for the subscription, the initial status is trialing, and the subscription automatically transitions to active when the trial ends and payment succeeds.

Handle the invoice

For subscriptions with collection_method set to charge_automatically, Stripe creates an invoice with the status open when you create the subscription. Your customer has 23 hours to pay. During this time, the subscription status is incomplete and the invoice status remains open. This 23-hour window accommodates customers who pay while on-session. If the customer returns to your application after 23 hours, create a new subscription for them.

For subscriptions with collection_method set to send_invoice, Stripe emails the customer a link to the invoice with a configurable due date. For subscriptions without a trial, the initial subscription status is active, even if the first invoice is unpaid.

To learn more, see Subscription invoices.

Confirm payment

For subscriptions with collection_method set to charge_automatically, if your customer pays the invoice, the subscription updates to active and the invoice to paid. Listen for the invoice.paid event or confirm that the subscription status is active.

Stripe sets the subscription’s current_period_start when it creates the initial invoice. Completing payment later doesn’t shift the start of the initial billing period. If a payment method requires customer action and the customer delays completing it, less time remains in the first billing period when you provision access.

For these subscriptions, if the customer doesn’t pay within 23 hours, the subscription updates to incomplete_expired and the invoice becomes void. To reactivate their access, create a new subscription.

For more details, see Subscription statuses and Payment statuses.

Provision access to your product

When a subscription becomes active, Stripe creates an active entitlement for each feature associated with the subscribed product. When a customer accesses your services, use their active entitlements to grant them access to the features included in their subscription.

Alternatively, track active subscriptions with webhook events and provision the product for the customer based on that activity.

Update the subscription

You can modify existing subscriptions as needed without having to cancel and recreate them. Some of the most significant changes you might make are upgrading or downgrading the subscription price or pausing payment collection for an active subscription.

For Stripe Checkout integrations, you can’t update the subscription or its invoice if the session’s subscription is incomplete. You can listen to the checkout.session.completed event to make the update after the session has completed. You can also expire the session instead if you want to cancel the session’s subscription, void the subscription invoice, or mark the invoice as uncollectible.

Handle unpaid subscriptions

If the customer doesn’t pay a subscription invoice, Stripe pauses further collection attempts. The subscription continues to generate invoices each billing period, which remain in draft status. The subscription’s status (past_due or unpaid) depends on your failed payment settings in the Dashboard.

Voided invoices don’t affect subscription status. Stripe determines the status from the most recent non-voided invoice. To learn more, see Failed subscription payments.

Cancel the subscription

You can cancel a subscription at any time, including at the end of a billing cycle or after a set number of billing cycles.

By default, canceling a subscription disables creating new invoices and stops automatic collection of all outstanding invoices from the subscription. It also deletes the subscription and you can no longer update it except for its metadata and cancellation_details. If your customer wants to resubscribe, you need to collect new payment information from them and create a new subscription.

Subscription statuses

Subscriptions can have the following statuses. The actions you can take on a subscription depend on its status.

Payment statuses

A PaymentIntent tracks the lifecycle of every payment. Whenever a payment is due for a subscription, Stripe generates an invoice and a PaymentIntent. The PaymentIntent ID attaches to the invoice and you can access it from the Invoice and Subscription objects.

The status of the PaymentIntent affects the status of the invoice and the subscription. Here’s how the different outcomes of a payment map to the different statuses:

Payment methods with delayed payment confirmation

Payment methods that can’t immediately return payment status when a customer attempts a transaction (for example, ACH Direct Debit) handle subscription status transitions differently. When you use these types of payment methods, a subscription can move directly to active after creation and bypass incomplete. If the payment fails later, Stripe voids the invoice but the subscription remains active. Use this behavior when you design your access control and retry logic.

The following sections describe outcomes for the initial payment when creating a subscription that requires immediate payment. For payment failures on later invoices, see Handle failed recurring payments.

Initial payment succeeded

When the customer’s initial subscription payment succeeds:

• The status of the PaymentIntent moves to succeeded.
• The status of the invoice is paid.
• The status of the subscription is active.
• Stripe sends an invoice.paid event to your configured webhook endpoints.

For payment methods with longer processing periods, subscriptions are immediately activated. In these cases, the status of the PaymentIntent might be processing for an active subscription until the payment succeeds.

When the subscription is activated, provision access to your product.

Initial payment requires a payment method

If the initial payment fails because of a card error such as a decline:

• The status of the PaymentIntent is requires_payment_method.
• The status of the subscription is incomplete.
• The status of the invoice is open.

To handle these scenarios:

• Notify the customer.
• Collect new payment information and confirm the PaymentIntent.
• Update the default payment method on the subscription.
• Stripe re-attempts payment using Smart Retries or based on your custom retry rules.
• Use the invoice.payment_failed event to monitor subscription payment failure events and retry attempt updates. After a payment attempt on an invoice, its next_payment_attempt value is set using the current subscription settings in your Dashboard.

Learn how to handle payment failures for subscriptions.

Handle failed recurring payments

When a recurring subscription payment fails, listen for invoice.payment_failed. Monitor subscription status changes to detect transitions to past_due or unpaid. Notify the customer so they can update their payment method or pay the open invoice. Verify webhook signatures before you process events.

Configure Smart Retries or custom retry rules to retry failed payments. In your failed payment settings, choose what happens to the subscription after the final retry. Use the subscription status table to determine when to revoke access and how to reactivate past_due and unpaid subscriptions. See Failed recurring charges for more details.

Requires action

Some payment methods require customer authentication with 3D Secure (3DS). Whether authentication is required depends on your Radar rules and the issuing bank for the card.

If payment fails because the customer needs to authenticate a payment:

• The status of the PaymentIntent is requires_action.
• The status of the subscription is incomplete.
• The status of the invoice is open.

To handle these scenarios:

• Monitor for the invoice.payment_action_required event notification with webhook endpoints. This indicates that authentication is required.
• Notify your customer that they must authenticate. Retrieve the PaymentIntent’s client secret and pass it to stripe.handleNextAction. This guides the customer through any required steps and returns the result to your application.
• Monitor the invoice.paid event on your event destination to verify that the payment succeeded. Users can leave your application before handleNextAction() finishes. Verifying whether the payment succeeded allows you to correctly provision your product.