How subscriptions work

With Subscriptions, customers make recurring payments for access to a product. Subscriptions require you to retain more information about your customers than one-time purchases because you need to charge them in the future.

Stripe offers many features that 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

This is what the recommended subscription flow looks like:

1. Create the subscription. The status of the subscription is incomplete if you follow these steps. If you create a subscription without specifying the payment_behavior, the default status is active.

2. Stripe automatically creates an invoice with the open status for the subscription.

3. The customer pays the first invoice.

4. When the payment succeeds:

   • The subscription status moves to active
   • The invoice status is set to paid
   • Stripe sends an invoice.paid event to your configured webhook endpoints

5. You provision access to your product. 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.

The status changes to trialing if you offer trials that don’t require payments. When the trial is over, the subscription moves to active and the subscribed customer starts to be charged.

Subscription payment behavior

To simplify handling failed payments, create subscriptions with payment_behavior set to default_incomplete. This creates subscriptions with status incomplete, which allows you to collect and confirm payment information in a single user interface. When using allow_incomplete or error_if_incomplete, Stripe immediately attempts to pay the invoice. If the payment fails, the subscription’s status changes to incomplete or the creation fails.

Successful payments

When your customer successfully pays the invoice, the subscription updates to active, and the invoice updates to paid. At this point, you can provision access to your product.

Payment window

Customers have about 23 hours to make a successful payment. The subscription remains in the incomplete status and the invoice is open during this time. If your customer pays the invoice, the subscription updates to active and the invoice updates to paid. If they don’t make a payment, the subscription updates to incomplete_expired and the invoice becomes void.

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

Failed payments

The subscription’s status remains active as long as automatic payments succeed. If automatic payment fails, the subscription updates to past_due and Stripe attempts to recover payment based on your retry rules. If payment recovery fails, you can set the subscription status to canceled, unpaid, or leave it past_due.

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 cycle, which remain in the draft state. 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 are treated as paid when determining subscription status, even though their paid property remains false. Stripe ignores voided invoices when determining subscription status; the most recent non-voided invoice is used instead.

The status of an unpaid subscription is based on your failed payment settings in the Dashboard.

Cancel subscriptions

If you cancel a subscription, it disables creating new invoices and stops automatic collection of all invoices from the subscription because it sets auto_advance to false. 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.

Change subscriptions

Stripe supports modifying existing subscriptions without having to cancel and recreate them. Some of the most significant changes you might make are upgrading or downgrading the subscription price, or canceling or pausing payment collection for an active subscription. Learn more about how to change existing subscriptions.

Manage Checkout Sessions

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.

Integration example

This section describes our sample integration on GitHub, which illustrates how to build a subscriptions integration. If you’re ready to build your own integration, see the Billing quickstart or integration guide.

Landing page

On your frontend, the landing page collects the email address first. Your application might have other customer-specific information you want to collect like a username or address. Clicking the signup button sends the information collected on the landing page to your backend. This process creates a customer and displays the pricing page on your frontend.

Pricing page

The pricing page displays your subscription options based on the products and prices you create when you first set up your integration, meaning you don’t need to create new ones every time customers sign up. Your pricing page displays the prices you created, and your customers choose the option they want. The example on GitHub displays a payment form when a customer selects an option. Learn more about products and prices.

Payment

The payment form collects a name and card information. Stripe hosts this form if you use Checkout. It’s one of the key features that allows you to collect payments and remain PCI compliant. Clicking Subscribe:

1. Creates a new subscription with your customer and price IDs.
2. Generates an invoice for your initial subscription cycle.
3. Collects payment details and pays your invoice.
4. Sets the payment method as the default payment method for the subscription-a requirement for subsequent payments.

Make sure to confirm payment before provisioning access for your customer.

To implement this:

• Accept payments without code: If you don’t want to write any code, learn how to create a Payment Link and share it with your customers.
• Build a checkout page: Use the Checkout Sessions API to accept payments through a hosted page, an embedded form on your site, or a customized checkout page built with embedded components.
• Advanced integration: Use Stripe Elements to collect payment details and activate the subscription with the Payment Element.

Provisioning

Use Entitlements to determine when you can grant or revoke product feature access to your customers. Alternatively, after a successful payment, you can safely provision the product for the customer. This generally means:

1. Verifying the status of the subscription is active.
2. Granting the customer access to the products and features they subscribed to.

Learn how to use event destinations to:

• Track active subscriptions
• Handle payment failures
• Check event objects

How payments work with subscriptions

To simplify the handling of failed payments and to create subscriptions before attempting payment:

1. Pass payment_behavior=default_incomplete when creating a subscription. If your subscription requires payment, it’s created with an incomplete status, otherwise your subscription immediately becomes active.

2. Activate an incomplete subscription by paying the first invoice.

3. Pass the payment intent identifier from the invoice to your user interface to collect payment information and confirm the payment intent. You can use Elements, the Android SDK, or the iOS SDK.

Recurring charges

Stripe handles recurring charges for you automatically. This includes:

• Automatically invoicing customers and attempting payments when new billing cycles start.
• When payments fail, Stripe retries them using the Smart Retries feature or your custom retry schedule. This automatically re-attempts payment according to your Dashboard settings when cards are declined. If a failure returns a hard decline code, the scheduled retries continue but the payment executes only if you obtain a new payment method.

You can send a dunning email to customers for overdue payments to increase recovery chances. For payments that require 3D Secure, you can configure your billing settings to send a hosted link to customers so they can complete the flow.

Payment status

The payment process differs across payment methods and geographical locations. Payments can also fail initially (for example, a customer might enter the wrong card number or have insufficient funds), so various payment outcomes are possible.

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 state of the PaymentIntent affects the state 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 your payment succeeds, the status of the PaymentIntent is succeeded, and the subscription becomes active. For payment methods with longer processing periods, subscriptions are immediately activated. In these cases, the status of the PaymentIntent may be processing for an active subscription until the payment succeeds.

With your subscription now activated, provision access to your product. Read the guide to learn more about the subscription lifecycle and best practices for provisioning.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "active",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "paid",
    "payments": {
      "data": [
        {
          "payment": {
            "type": "payment_intent",
            "payment_intent": {
              "status": "succeeded",
              ...
            }
          }
          ...
        }
      ],
    ...
  }
}

Requires payment method

If payment fails because of a card error, such as a decline, the status of the PaymentIntent is requires_payment_method and the subscription is incomplete.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "incomplete",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "open",
    "payments": {
      "data": [
        {
          "payment": {
            "type": "payment_intent",
            "payment_intent": {
              "status": "requires_payment_method",
              ...
            }
          }
          ...
        }
      ],
      ...
    }
  }
}

To resolve these scenarios:

• Notify the customer.
• Collect new payment information and confirm the payment intent.
• Update the default payment method on the subscription.

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. If you use the Payment Intents API, the status value of the PaymentIntent is requires_action when a customer needs to authenticate a payment. You can get the PaymentIntent on the Invoice Payment resource either by expanding latest_invoice.payments.data.payment.payment_intent or by specifying the invoice parameter with Invoice Payment list. 3DS completes the authentication process. Whether a payment method requires authentication depends on your Radar rules and the issuing bank for the card.

Regulations in Europe often require 3D Secure. See Strong Customer Authentication to determine whether handling this status is important for your business. If you have an existing billing integration and want to add support for this flow, also see the Billing SCA Migration guide.

{
  "id": "sub_1ELI8bClCIKljWvsvK36TXlC",
  "object": "subscription",
  "status": "incomplete",
  ...
  "latest_invoice": {
    "id": "in_EmGqfJMYy3Nt9M",
    "status": "open",
    ...
    "payments": {
      "data": [
        {
          "payment": {
            "type": "payment_intent",
            "payment_intent": {
              "status": "requires_action",
              "client_secret": "pi_91_secret_W9",
              "next_action": {
                "type": "use_stripe_sdk",
                ...
              },
              ...
            }
          }
          ...
        }
      ],
    }
  }
}

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

Subscription statuses

Subscription settings and recovery

Your subscription settings determine how Stripe responds when payments fail or when subscriptions become past due.

Smart Retries

After you create a subscription, payment failure is the most important event that can happen. Failures can occur for many reasons:

• Lack of a payment method on the customer.
• The payment method is expired.
• The payment is declined.

You can configure Stripe to retry failed payments for up to two months in Manage failed payments for subscriptions in the Dashboard. Smart Retries uses AI to pick the optimal time for retries over the configured period.

You can also modify the retry schedule with custom rules. You can configure up to three retries, each with a specific number of days after the previous attempt.

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

If recovery fails, the subscription transitions according to your settings. The options are:

After the final payment attempt, we make no further payment attempts. Changing your subscription settings only affects future retries.

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 we send the invoice.upcoming event for subscriptions set up to collect payment automatically.
• A failed payment notification prompting customers to update their payment information. Learn how to turn on failed payment notifications.
• An expiring card notification when a customer’s default_source card is due to expire.

You can customize the logos and colors your customers see in emails, and our Hosted Invoice Payment page by changing the branding settings in the Dashboard.

Trials

Card networks require you to inform your customers about their trials. Stripe can manage this communication for you. In the Dashboard, you can configure the cancellation URL that’s included on both the reminder emails and on the receipt for the first invoice after a trial ends. You can also configure the statement descriptor for the first charge after a trial. Learn more about these requirements and settings on the trials page.

Subscription objects

Use the following core API resources to build and manage subscriptions:

Here’s an example of how products, features, and entitlements work together. Imagine that you want to set up a subscription service that offers two tiers: a standard product with basic functionality, and an advanced product that adds extended functionality.

1. You create two features: basic_features and extended_features.
2. You create two products: standard_product and advanced_product.
3. For the standard product, you create one ProductFeature that associates basic_features with standard_product.
4. For the advanced product, you create two ProductFeatures: one that associates basic_features with advanced_product and one that associates extended_features with advanced_product.

A customer, first_customer, subscribes to the standard product. When you create the subscription, Stripe automatically creates an Entitlement that associates first_customer with basic_features.

Another customer, second_customer, subscribes to the advanced product. When you create the Subscription, Stripe automatically creates two Entitlements: one that associates second_customer with basic_features, and one that associates second_customer with extended_features.

You can determine which features to provision for a customer by retrieving their active entitlements or listening to the Active Entitlement Summary event. You don’t have to retrieve their subscriptions, products, and features.

Subscription events

Events are triggered every time a subscription is created or changed. We send some events immediately when a subscription is created, while others recur on regular billing intervals. We recommend listening for events with webhook endpoints.

Make sure that your integration properly handles the events. For example, you might want to email a customer if a payment fails or revoke a customer’s access when a subscription is canceled.

See Subscription events for a list of the most common subscription-related events and, where applicable, suggested actions for handling the events.