# Let customers pause subscriptions in the customer portal

Allow customers to pause and resume their own subscriptions for a duration you choose.

In the customer portal, you can let your customers pause their subscriptions for a duration you choose, and resume them automatically at the end of that duration. Customers can pause subscriptions only in the redesigned customer portal.

When a subscription pauses, its status changes to `paused`, and Stripe stops generating invoices and advancing billing periods until it resumes. This is different from [pausing payment collection](https://docs.stripe.com/billing/subscriptions/pause-payment.md), where the subscription stays active. Learn more about [how pausing a subscription works](https://docs.stripe.com/billing/subscriptions/pause.md).

Stripe doesn’t control access to your service. You’re responsible for suspending access when a subscription pauses and restoring it when the subscription resumes. See [Handle pause and resume events](https://docs.stripe.com/customer-management/pause-subscriptions.md#webhooks).

## Eligibility 

Customers can pause a subscription in the portal only if it meets all of these conditions:

- It uses [flexible billing mode](https://docs.stripe.com/billing/subscriptions/billing-mode.md).
- It uses the `charge_automatically` [collection method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method).
- Its status is `active` or `past_due`. Customers can’t pause subscriptions that are `trialing`, `incomplete`, `unpaid`, `canceled`, or already `paused`.
- It doesn’t have an active [trial offer](https://docs.stripe.com/billing/subscriptions/trials.md).
- It isn’t scheduled to cancel.
- It doesn’t have an attached [subscription schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md). This includes schedules that the portal creates when a customer schedules a downgrade with [Manage downgrades](https://docs.stripe.com/customer-management/configure-portal.md#downgrades).

- In live mode, it hasn’t paused in the last 12 months. Customers can pause each subscription once every 12 months.

These conditions build on the general [limits for pausing subscriptions](https://docs.stripe.com/billing/subscriptions/pause.md#limitations).

## Enable pausing 

Turn on pausing and choose the durations customers can pause for in the Dashboard or with the API.

#### Dashboard

To let customers pause subscriptions in the Dashboard:

1. Go to the [Customer portal settings](https://dashboard.stripe.com/settings/billing/portal) page.
2. Expand the **Pause** section and turn on **Pause subscriptions**.
3. Under **Pause durations**, click **Add duration** to add each duration that customers can choose from.
4. Click **Save**.

#### API

To let customers pause subscriptions with the API, set `features.subscription_pause.enabled` to `true` when you [create](https://docs.stripe.com/api/customer_portal/configurations/create.md) or [update](https://docs.stripe.com/api/customer_portal/configurations/update.md) a portal configuration. Use `features.subscription_pause.duration.interval_options` to set the durations customers can choose from.

By default, customers can pause for one month. You can offer up to five unique durations, and each duration can be up to three years long.

The following example lets customers pause for one month or three months:

```curl
curl https://api.stripe.com/v1/billing_portal/configurations \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "features[subscription_pause][enabled]=true" \
  -d "features[subscription_pause][duration][type]=interval_options" \
  -d "features[subscription_pause][duration][interval_options][0][interval]=month" \
  -d "features[subscription_pause][duration][interval_options][0][interval_count]=1" \
  -d "features[subscription_pause][duration][interval_options][1][interval]=month" \
  -d "features[subscription_pause][duration][interval_options][1][interval_count]=3"
```

## What customers see 

When pausing is enabled, eligible subscriptions show a pause action in the portal:

1. **Choose a duration**: The customer selects one of your pause durations. The summary shows the date the plan pauses, which is the end of the current billing period, and the date it resumes. It also shows any payment method or invoice requirements before the customer confirms.
2. **Before the pause starts**: The subscription keeps its current status, and the customer can keep using your service until the pause date. The portal shows when the subscription pauses and when it resumes. To cancel the scheduled pause, the customer clicks **Remove upcoming pause** before the pause date.
3. **While paused**: The customer can resume early or cancel the subscription. They can’t change their plan while the subscription is paused. If a resumption payment is pending, the customer can’t resume until that payment completes.

## How the portal pauses and resumes subscriptions 

When a customer pauses a subscription, the portal creates a [subscription schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) with a [pause schedule](https://docs.stripe.com/billing/subscriptions/pause/schedules.md). The pause starts at the end of the current billing period.

The pause schedule resumes the subscription automatically at the end of the duration the customer chose. The portal uses these resume settings:

- `resume_at.type` is `duration`.
- `billing_cycle_anchor` is `resume_at`, so a new billing period starts on the resume date.
- `payment_behavior` is `resume_on_payment_success`, so the subscription resumes only after the resumption payment succeeds.
- `proration_behavior` is `create_prorations`.

The subscription stays `paused` until the resumption payment succeeds, even after the resume date. Check the subscription’s `status` to determine whether it has resumed instead of relying on the resume date. Learn more about [scheduled resume behavior](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#configure-scheduled-resume-behavior).

Pausing doesn’t void existing invoices. Stripe continues attempting to collect on invoices created before the pause.

## Handle pause and resume events 

Listen for the following events to keep access to your service in sync with the subscription. Before you process them, [verify their signatures](https://docs.stripe.com/webhooks.md#verify-events) to confirm they came from Stripe.

| Event | Description |
| --- | --- |
| [subscription_schedule.created](https://docs.stripe.com/api/events/types.md#event_types-subscription_schedule.created) | Occurs when a customer schedules a pause and the portal creates a subscription schedule. The subscription stays active until the pause date, so don’t suspend access yet. |
| [subscription_schedule.updated](https://docs.stripe.com/api/events/types.md#event_types-subscription_schedule.updated) or [subscription_schedule.released](https://docs.stripe.com/api/events/types.md#event_types-subscription_schedule.released) | Occurs when a customer cancels a scheduled pause or resumes a paused subscription early. |
| [customer.subscription.paused](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.paused) | Occurs when the pause takes effect and the subscription’s status changes to `paused`. Suspend access to your service when you receive this event. |
| [customer.subscription.resumed](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.resumed) | Occurs when the subscription resumes, either automatically after the resumption payment succeeds or because the customer resumed it early. Restore access to your service when you receive this event. |

Stripe also sends [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) when the subscription pauses or resumes. Learn more about [pause and resume events](https://docs.stripe.com/billing/subscriptions/pause.md#identify-pause-and-resume-events).

## Deep link to the pause flow 

To send customers directly to the pause flow for a specific subscription, create a portal session with the `subscription_pause` [flow type](https://docs.stripe.com/customer-management/portal-deep-links.md#flow-types).

## Test pausing 

To test pausing and resuming in the portal:

1. Turn on pausing in the [Customer portal settings](https://dashboard.stripe.com/test/settings/billing/portal) of a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes).
2. Create an eligible subscription for a customer that uses a [test clock](https://docs.stripe.com/billing/testing.md#test-clocks).
3. On the customer’s page, click the overflow menu ⋯. Under **Actions**, select **Open customer portal**.
4. Pause the subscription in the portal.
5. Advance the test clock to the pause date, then to the resume date. Confirm that your integration suspends and restores access when it receives `customer.subscription.paused` and `customer.subscription.resumed`.

The once-every-12-months limit applies only in live mode, so you can pause the same subscription multiple times in a sandbox.