How subscriptions work

Subscriptions allow customers to make recurring payments for access to a product. Unlike one-time purchases, subscriptions require you to store additional customer information for future charges. Stripe provides various features to help you manage subscription billing:

• Support for different pricing models
• Subscription discount management
• Trial management
• Prorations for modified subscriptions
• Customer self-service management
• Invoicing to collect payments
• Automated revenue recovery
• Reporting and analytics

The subscription lifecycle

The process of creating and managing subscriptions relies on core Stripe API resources, including Customers, Invoices, and PaymentIntents. For the full list of subscription-related resources, see API object definitions.

This is what the recommended subscription flow looks like:

Create the subscription

Create a new subscription in the Dashboard or with the API. Every time you create a subscription, this triggers an event. Listen for these events with webhook endpoints, and make sure that your integration properly handles them.

Optionally, create a trial that doesn’t require payment for the subscription. In this case, the status is trialing. When the trial is over, the subscription moves to active and Stripe charges the subscribed customer.

Payment behavior

We recommend you set the payment_behavior of a subscription to default_incomplete to help handle failed payments and complex payment flows like 3DS. This creates subscriptions with status incomplete if payment is required, which allows you to subsequently collect and confirm payment information to activate the subscription.

When you set payment_behavior to:

• allow_incomplete: Stripe immediately attempts to collect payment on the invoice. If the payment fails, the subscription’s status changes to incomplete.
• error_if_incomplete: If payment fails, the subscription creation fails entirely.

Subscriptions you create in the Dashboard default to the appropriate payment behavior depending on the payment method.

Handle the invoice

When you create a subscription, Stripe automatically creates an invoice with the status open. Your customer has about 23 hours to make a successful payment. During this time, the subscription status is incomplete and the invoice status remains open. The 23-hour window exists because your customer usually makes the first payment for a subscription while on-session. If the customer returns to your application after 23 hours, create a new subscription for them.

The customer pays

If your customer pays the invoice, the subscription updates to active and the invoice to paid. If they don’t make a payment, the subscription updates to incomplete_expired and the invoice becomes void.

To confirm whether the invoice has been paid:

• Set up a webhook endpoint or another type of event destination and listen for the invoice.paid event.
• Manually check the subscription object and look for subscription.status=active. The status becomes active when the invoice has been paid either through an automatic charge or having the customer pay manually.

For more details, see Subscription statuses and Payment statuses.

Provision access to your product

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

Alternatively, you can use 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.

You can listen to subscription events with webhook endpoints for changes to the subscription. For example, you might want to email a customer if a payment fails or revoke a customer’s access when they cancel their 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.

Update the first invoice

You can update the first invoice for a subscription if the collection_method is send_invoice. After the invoice is created, you have one hour to make any updates to the amounts, line items, description, metadata, and so on. You can’t update the invoice after it’s finalized and sent to the customer for payment.

The first invoice for a subscription with the collection_method set to charge_automatically is finalized and charged immediately. You can’t update the first invoice before it’s finalized, but you can update subsequent invoices for subscription renewals.

You also can’t update the first invoice for subscription schedules. The first invoice is always open, regardless of the collection method.

Handle unpaid subscriptions

For subscriptions with unpaid invoices, the unpaid invoices remain open but further payment attempts are paused. The subscription continues to generate invoices each billing period, which remain in the draft status. To reactivate the subscription:

1. Collect new payment information if necessary.
2. Enable automatic collection by setting auto_advance to true on draft invoices.
3. Finalize and pay the open invoices. Paying the most recent non-voided invoice before its due date updates the subscription status to active.

Invoices marked as uncollectable keep the underlying subscription active. Stripe ignores voided invoices when determining subscription status and uses the most recent non-voided invoice instead.

The unpaid subscription’s status depends on your failed payment settings in the Dashboard.

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, cancelling 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 the subscription or its metadata. 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:

The following sections explain these statuses and the actions to take for each.

Payment succeeded

When the customer’s payment is successful:

• The status of the PaymentIntent moves to succeeded.
• The status of the subscription is active.
• The status of the invoice is paid.
• 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.

With your subscription now activated, provision access to your product.

Requires payment method

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

Requires action

Some payment methods require customer authentication with 3D Secure (3DS) to complete the payment process. 3DS completes the authentication process. Whether a payment method requires authentication 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 client secret for the PaymentIntent and pass it in a call to stripe.ConfirmCardPayment. This displays an authentication modal to your customers, attempts payment, then closes the modal and returns context to your application.
• Monitor the invoice.paid event on your event destination to verify that the payment succeeded. Users can leave your application before confirmCardPayment() finishes. Verifying whether the payment succeeded allows you to correctly provision your product.