# Pause subscriptions after payment failure

Pause eligible subscriptions after the first renewal payment failure or the final failed payment attempt.

Pause subscriptions after a payment failure to stop service delivery and invoice generation without canceling the customer relationship. You can pause after the first renewal payment failure on a renewal invoice or after Stripe finishes the configured [payment retry schedule](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md).

The first-renewal-payment-failure action doesn’t apply to the initial invoice created for a subscription.

> Learn about the difference between [pausing a subscription and pausing payment collection](https://docs.stripe.com/billing/subscriptions/pause.md).

## Eligibility

Payment-failure settings apply globally to your account, but only eligible subscriptions that use [flexible billing mode](https://docs.stripe.com/billing/subscriptions/billing-mode.md) can pause. See [pause subscription limitations](https://docs.stripe.com/billing/subscriptions/pause.md#limitations) for all eligibility requirements.

> When pause is the configured action and Stripe can’t pause the subscription after the first failed payment attempt, the subscription remains `past_due`. If Stripe can’t pause it after the final failed payment attempt, Stripe cancels the subscription instead.

## Configure pause timing

You can configure Stripe to pause:

- **After the first renewal payment failure**: Stripe pauses after the first failed payment attempt on a renewal invoice. This action doesn’t apply to the initial subscription invoice.
- **After retries are exhausted**: Stripe runs the configured retry schedule and pauses after the final failed payment attempt.

If retries are disabled, pausing after the first renewal payment failure doesn’t apply. Stripe applies only the configured final payment failure action.

Neither pause timing applies to an invoice associated with a [pending subscription update](https://docs.stripe.com/billing/subscriptions/pending-updates.md). If that invoice fails, Stripe doesn’t pause or cancel the subscription. The existing subscription remains `active`.

To configure pause timing in the Dashboard:

1. In the Dashboard, open **Billing** > **Revenue recovery** > [Retries](https://dashboard.stripe.com/revenue_recovery/retries).
2. Find **Subscription status**.
3. For **If all retries for a payment fail**, select **Pause the subscription** to pause after the final failed attempt. To pause only after the first renewal payment failure, select **Cancel the subscription** instead.
4. For **When the first payment attempt for a renewal fails**, select **Pause the subscription** if you want to pause on the first renewal payment failure. Select it in both controls if you want both pause timings.

> If you enable pausing after the first renewal payment failure, you must set the final payment failure action to **Cancel the subscription** or **Pause the subscription**.

## Behavior while paused

When Stripe pauses the subscription:

- The subscription changes to `paused`.
- Stripe captures outstanding metered usage through the pause time as a pending invoice item.
- After a first-renewal-payment-failure pause, Stripe creates a pending invoice item that credits licensed time from each item’s current period start through the end of the period.
- After a final-payment-failure pause, Stripe doesn’t create an unused-time credit.
- Stripe doesn’t create an invoice at pause time. Any billed items appear on the next invoice.
- The invoice that caused the pause remains `open`.
- Stripe doesn’t generate new subscription invoices.
- Additional failed attempts on the invoice don’t change the subscription to `past_due`.

If the subscription has an attached subscription schedule, Stripe replaces any existing value in the schedule’s [pause_schedules](https://docs.stripe.com/api/subscription_schedules.md#subscription_schedule_object-pause_schedules) attribute with an open-ended pause that begins when the subscription pauses. The schedule retains its configured phases and initially has no scheduled resume date. If resolving the invoice triggers automatic resumption, Stripe adds an immediate resume entry to the pause schedule that it created and applies the configured billing cycle anchor behavior.

For more information about the paused status and its effect on invoicing, see [Pause subscriptions](https://docs.stripe.com/billing/subscriptions/pause.md).

## Configure resume behavior

You can configure the subscription to resume automatically after the invoice that caused the pause is settled, or leave it paused until you resume it. When you enable automatic resumption, choose whether Stripe sets the billing cycle anchor to the resumption time or keeps the existing anchor.

1. In the Dashboard, open **Billing** > **Revenue recovery** > [Retries](https://dashboard.stripe.com/revenue_recovery/retries).
2. Find **Subscription status**.
3. Select **Pause the subscription** for the first renewal payment failure or the final action to show the resumption controls.
4. For **When the invoice that triggered the pause is paid or manually marked uncollectible**, select **Resume the subscription** to start a resume attempt automatically, or **Leave the subscription paused** to resume it manually later.
5. If you chose **resume the subscription** and want a new billing cycle beginning on the resumption date, enable **Reset billing cycle anchor to resumption date**. Otherwise, leave it off to keep the existing billing cycle anchor. This switch appears only when automatic resumption is selected.

### Resume automatically

Automatic resumption can involve resolving two invoices:

1. The invoice that caused the pause must be paid or manually marked `uncollectible`. This starts the resume attempt and conditionally creates a resumption invoice if it’s possible to debit.
2. If Stripe creates a resumption invoice, it includes any outstanding usage for both pause types and an unused-time credit only for a first-renewal-payment-failure pause. The resumption invoice must be paid or manually marked `uncollectible` to resume the subscription.

> When you test automatic resumption with a [test clock](https://docs.stripe.com/billing/testing/test-clocks.md), advance the clock again after you pay the invoice that caused the pause or manually mark it `uncollectible`. Stripe starts the resume attempt on the next clock advance, so the subscription remains `paused` until then. When you pay the resumption invoice or manually mark it `uncollectible`, the subscription resumes immediately without another clock advance.

The subscription doesn’t automatically resume when:

- Stripe automatically marks the invoice that caused the pause `uncollectible` as the final payment failure action.
- Another invoice for the customer is paid.
- A revision of the invoice that caused the pause is paid.
- The invoice that caused the pause is voided. You must resume the subscription manually.

### Resume manually

With manual resumption, resolving the invoice doesn’t change the subscription status. The subscription remains `paused` until you [resume it](https://docs.stripe.com/billing/subscriptions/pause.md#resume-a-subscription).

## Identify a payment-failure pause

The [status_details.paused.subscription.type](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-status_details-paused-subscription-type) attribute identifies why a subscription paused:

- `first_payment_failure`: Stripe paused the subscription after the first failed payment attempt on a renewal invoice.
- `final_payment_failure`: Stripe paused the subscription after the final failed payment attempt.