# Pause subscriptions

Pause a subscription to suspend service delivery and invoice generation.

Make clear that pausing a subscription stops both service delivery and invoice generation for the customer. If the user wants the customer to retain access to the service, direct them to [pause payment collection](https://docs.stripe.com/billing/subscriptions/pause-payment.md) instead.

Pause a subscription to temporarily suspend service delivery and invoice generation without canceling it. This is useful for customers who are on vacation, won’t use the service for an extended period, or need a temporary hold. It also gives you a paused state for retention flows, support tooling, and testing billing, entitlement, and webhook behavior.

If you want to keep your customer’s access to the service active while temporarily stopping payment collection, use [pause payment collection](https://docs.stripe.com/billing/subscriptions/pause-payment.md) instead.

## Before you begin

- [Review the conditions for when you can’t pause a subscription](https://docs.stripe.com/billing/subscriptions/pause.md#limitations).
- If a subscription uses a coupon, the coupon retains its original validity period. Its duration continues to run while the subscription is paused.
- A subscription can also move to the `paused` status when a trial ends without a payment method on file. Stripe does this automatically and doesn’t use the Pause subscription endpoint. For more details, see [Trial end without a payment method](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment).

## Pause a subscription

You can pause subscriptions with either the [API](https://docs.stripe.com/api/subscriptions/pause.md?api-version=preview) or in the [Dashboard](https://dashboard.stripe.com/subscriptions). Subscriptions must use [flexible billing mode](https://docs.stripe.com/billing/subscriptions/billing-mode.md), and the pause subscription endpoint requires API version `2025-06-30.preview` or later. The pause takes effect immediately.

#### Dashboard

To pause a subscription in the Dashboard:

1. On the [Subscriptions page](https://dashboard.stripe.com/subscriptions) in the Dashboard, find the subscription, click the overflow menu (⋯), and select **Pause subscription**.
2. Configure billing behavior for unused time and outstanding usage. To learn about each option, see [How pausing affects billing](https://docs.stripe.com/billing/subscriptions/pause.md#how-pausing-affects-billing).
3. Click **Pause subscription**.

#### API

The [bill_for.unused_time_from](https://docs.stripe.com/api/subscriptions/pause.md?api-version=2026-07-29.preview#pause_subscription-bill_for-unused_time_from) and [bill_for.outstanding_usage_through](https://docs.stripe.com/api/subscriptions/pause.md?api-version=2026-07-29.preview#pause_subscription-bill_for-outstanding_usage_through) parameters control billing behavior at pause time. To learn about each parameter, see [How pausing affects billing](https://docs.stripe.com/billing/subscriptions/pause.md#how-pausing-affects-billing).

To pause an active subscription using the API:

```curl
curl https://api.stripe.com/v1/subscriptions/sub_1234567890/pause \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -d "bill_for[unused_time_from][type]=now" \
  -d "bill_for[outstanding_usage_through][type]=now" \
  -d invoicing_behavior=pending_invoice_item
```

### After you pause a subscription

- The subscription status changes to `paused`.
- The [current_period_end](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items-data-current_period_end) updates to the time you paused the subscription.
- Stripe pauses invoice generation until you resume the subscription. Existing invoices continue to advance without affecting the subscription’s paused status.
- Stripe sends the [customer.subscription.paused](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.paused), [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated), and [entitlements.active_entitlement_summary.updated](https://docs.stripe.com/api/events/types.md#event_types-entitlements.active_entitlement_summary.updated) webhooks so you can de-provision service access.
- The [customer portal](https://docs.stripe.com/customer-management.md) shows that the subscription is paused, but subscribers can’t use the portal to pause subscriptions themselves.

### How pausing affects billing

Use the [bill_for](https://docs.stripe.com/api/subscriptions/pause.md?api-version=preview#pause_subscription-bill_for) parameter to control how Stripe handles unused licensed time and outstanding metered usage in the current period.

**Credit for unused licensed time**

Set `unused_time_from` to control how much unused licensed time Stripe credits:

| Value | Behavior |
| --- | --- |
| `now` (Default) | Credit unused time from when you pause the subscription through the end of the period. |
| `item_current_period_start` | Credit unused time from each item’s current period start through the end of the period. |
| `none` | Don’t credit unused time. |

**Charges for outstanding metered usage**

Set `outstanding_usage_through` to control how much metered usage Stripe bills:

| Value | Behavior |
| --- | --- |
| `now` (Default) | Bill for metered usage from the current period start through the time you pause the subscription. |
| `none` | Don’t bill for metered usage in the current period. |

The `invoicing_behavior` parameter controls whether Stripe invoices these credits and debits immediately (`invoice`) or adds them as pending invoice items (`pending_invoice_item`, the default). See [Preview the invoice before pausing](https://docs.stripe.com/billing/subscriptions/pause.md#preview-the-invoice-before-pausing).

## Subscription response

After you pause a subscription, the response includes a `status_details` object that provides information about when and why the subscription status was set to `paused`:

```json
{
  "id": "sub_1SrpWtRnJ89Z4rKknfSwXkBc",
  "object": "subscription",
  "status": "paused",
  "status_details": {
    "paused": {
      "subscription": {
        "type": "pause_requested"
      },
      "transitioned_at": 1749081600,
      "type": "subscription"
    }
  }
}
```

In the response:

- `status_details.paused.transitioned_at` is the Unix timestamp when the subscription transitioned to `paused`.

- `status_details.paused.subscription.type` explains why the subscription paused. Possible values include:

  - `pause_requested`: You paused the subscription using the API.
  - `trial_end_without_payment_method`: The trial ended without a payment method on file.
  - `system`: Stripe paused the subscription automatically.

## Preview the invoice before pausing

Use [Create a preview invoice](https://docs.stripe.com/api/invoices/create_preview.md?api-version=preview) to see the debits or credits that would be created by pausing.

Stripe returns a preview invoice only when:

- The `invoicing_behavior` is set to `invoice`. The default value (`pending_invoice_item`) doesn’t generate an invoice, so the endpoint returns a `404`.
- The `bill_for` parameters must produce billable amounts such as unused licensed time or outstanding metered usage. If pausing wouldn’t create debits or credits, no invoice exists to preview and the endpoint returns a `404`.

Stripe returns a preview invoice without modifying the subscription. Call [Pause a subscription](https://docs.stripe.com/api/subscriptions/pause.md?api-version=preview) when you’re ready.

Include `expand: ["parent.subscription_details.subscription"]` to see the projected subscription state after pausing: `status` is `paused`, `status_details` is populated, each item’s `current_period_end` is truncated to the pause time, and any pending updates are cleared. These changes don’t persist.

Preview the invoice for a pause that bills unused time and metered usage:

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -d subscription=sub_1234567890 \
  -d "subscription_details[pause][invoicing_behavior]=invoice" \
  -d "subscription_details[pause][bill_for][unused_time_from][type]=now" \
  -d "subscription_details[pause][bill_for][outstanding_usage_through][type]=now" \
  -d "expand[]=parent.subscription_details.subscription"
```

## Resume a subscription

To resume a subscription, it must use the [charge_automatically](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) collection method.

If resuming doesn’t generate an invoice, the subscription becomes `active` immediately. If Stripe generates an invoice, it finalizes the invoice immediately. The subscription becomes active once the invoice is paid or marked uncollectible. If you void the invoice, the subscription remains paused.

Use the optional [payment_behavior](https://docs.stripe.com/api/subscriptions/resume.md?api-version=preview#resume_subscription-payment_behavior) parameter to control how Stripe handles payment after you resume the subscription. To learn more, see [Payment behavior after resuming a subscription](https://docs.stripe.com/billing/subscriptions/pause.md?pause-dashboard-or-api=dash#payment-behavior-after-resuming-a-subscription).

#### Dashboard

To resume a paused subscription in the Dashboard:

1. On the [Subscriptions](https://dashboard.stripe.com/subscriptions) page, find the paused subscription, click the overflow menu (⋯), and select **Resume subscription**.
2. Configure proration and billing cycle anchor settings.
3. Click **Resume subscription**.

#### API

To resume a paused subscription:

```curl
curl https://api.stripe.com/v1/subscriptions/sub_1234567890/resume \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -d payment_behavior=resume_on_payment_success \
  -d billing_cycle_anchor=now \
  -d proration_behavior=create_prorations
```

> If your billing settings automatically void failed invoices, a failed resumption invoice can leave the subscription in `paused` status with no error returned. The resume request returns `200` and the subscription stays `paused`. Check your [billing settings](https://dashboard.stripe.com/settings/billing/automatic) if a subscription remains paused after a successful resume call.

### Payment behavior after resuming a subscription

After the subscription status updates to `active`:

- Invoicing resumes
- You can optionally reset the billing cycle anchor
- Stripe notifies you of the status change using the following webhooks so you can re-provision service access:
  - [customer.subscription.resumed](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.resumed)
  - [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated)
  - [entitlements.active_entitlement_summary.updated](https://docs.stripe.com/api/events/types.md#event_types-entitlements.active_entitlement_summary.updated)

Use the optional [payment_behavior](https://docs.stripe.com/api/subscriptions/resume.md?api-version=preview#resume_subscription-payment_behavior) parameter to control how Stripe handles payment after you resume the subscription.

| Criterion | `resume_on_payment_attempt` (Default) | `resume_on_payment_success` (Recommended) |
| --- | --- | --- |
| Resume request attempts payment | No. Collect payment with the [Pay invoice](https://docs.stripe.com/api/invoices/pay.md) endpoint. | Yes, when the customer has a default payment method or their cash balance covers the amount due. Otherwise, Stripe returns an error. |
| Subscription status if a payment attempt fails | `past_due`. The subscription doesn’t automatically revert to `paused`. | `paused` |
| Invoice payment retries after payment failure | No | Yes, unless your retry settings disable it |
| Pending update expiration time | 23 hours after the resume request | 1 year after the resume request |

## Preview the invoice before resuming a subscription

Use [Create a preview invoice](https://docs.stripe.com/api/invoices/create_preview.md?api-version=preview) to preview the resumption invoice before resuming. Set `subscription_details.resume_at` to `now`. Stripe returns a preview invoice without modifying the subscription.

Preview a resumption invoice using the same parameters you’ll pass to the resume call:

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -d subscription=sub_1234567890 \
  -d "subscription_details[resume_at]=now" \
  -d "subscription_details[billing_cycle_anchor]=now" \
  -d "subscription_details[proration_behavior]=create_prorations"
```

## Identify pause and resume events

Stripe sends the following events for paused and resumed subscriptions.

| Event | Description |
| --- | --- |
| [customer.subscription.paused](https://docs.stripe.com/api/events/types.md?api-version=preview#event_types-customer.subscription.paused) | Emitted when a subscription pauses. |
| [customer.subscription.resumed](https://docs.stripe.com/api/events/types.md?api-version=preview#event_types-customer.subscription.resumed) | Emitted when a subscription resumes. |
| [customer.subscription.updated](https://docs.stripe.com/api/events/types.md?api-version=preview#event_types-customer.subscription.updated) | Emitted when a subscription pauses or resumes. |
| [entitlements.active_entitlement_summary.updated](https://docs.stripe.com/api/events/types.md?api-version=preview#event_types-entitlements.active_entitlement_summary.updated) | Emitted when entitlements change due to a pause or resume. |

Example webhook payload for `customer.subscription.paused` (key fields shown):

```json
{
  "id": "evt_1SrpXjRnJ89Z4rKkFxe9waAz",
  "object": "event",
  ...
  "data": {
    "object": {
      "id": "sub_1SrpWtRnJ89Z4rKknfSwXkBc",
      "object": "subscription",
      ...
      "latest_invoice": "in_1SrpWtRnJ89Z4rKkzYBCF1MY",
      ...
      "status": "paused",
      ...
    }
  },
  ...
  "type": "customer.subscription.paused"
}
```

## Example: pause and resume mid-cycle

**Setup**: A customer has a monthly subscription at 30 USD. The billing cycle renews on day 30.

**Pause on day 15**: Call the pause endpoint with `bill_for.unused_time_from: { type: "now" }` and `invoicing_behavior: "pending_invoice_item"` (defaults).

- Stripe creates a -15 USD pending invoice item (credit for 15 unused days).
- The subscription transitions to `paused`.

```curl
curl https://api.stripe.com/v1/subscriptions/sub_1234567890/pause \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -d "bill_for[unused_time_from][type]=now" \
  -d invoicing_behavior=pending_invoice_item
```

**Resume on day 45** with `payment_behavior: "resume_on_payment_success"`, `billing_cycle_anchor: "now"`, and `proration_behavior: "create_prorations"`:

- Stripe creates a resumption invoice.
- The -15 USD credit from the pause and a 30 USD charge for the new billing period appear as line items.
- Net charge: 15 USD.
- Once paid, the subscription transitions to `active` and a new 30-day billing cycle begins.

```curl
curl https://api.stripe.com/v1/subscriptions/sub_1234567890/resume \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-06-24.preview" \
  -d payment_behavior=resume_on_payment_success \
  -d billing_cycle_anchor=now \
  -d proration_behavior=create_prorations
```

**Next renewal on day 75**: Stripe invoices the full 30 USD.

## Test with test clocks

Pause and resume behavior is time-dependent. Use [test clocks](https://docs.stripe.com/billing/testing/test-clocks.md) to simulate time in your test environment.

Test clocks let you:

- Trigger billing cycle events and confirm that invoices are generated correctly after resuming.
- Verify that `customer.subscription.paused` and `customer.subscription.resumed` webhooks fire at the correct points.
- Test coupon expiration behavior across a pause period.
- Confirm that your entitlement revocation and re-provisioning logic fires correctly.

## Query paused subscriptions in Sigma

The `subscriptions` table in [Sigma](https://dashboard.stripe.com/sigma/queries) has a `status` column and a `status_details` JSON column for identifying and analyzing paused subscriptions.

Use this query to find all paused subscriptions with their pause reason and timestamp:

```sql
select
  id,
  customer_id,
  status,
  json_extract_scalar(status_details, '$.paused.subscription.type') as pause_reason,
  from_unixtime(cast(json_extract_scalar(status_details, '$.paused.transitioned_at') as double)) as paused_at
from subscriptions
where status = 'paused'
order by paused_at desc
```

## Subscriptions you can’t pause 

You can’t pause a subscription if it meets any of these conditions:

| Condition | How to reach a pausable state |
| --- | --- |
| Uses [send_invoice](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) collection | [Update the subscription](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-collection_method) to use `charge_automatically` collection. |
| Uses [classic billing mode](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_mode-type) | Migrate to [flexible billing mode](https://docs.stripe.com/billing/subscriptions/billing-mode.md). |
| Status `trialing` | Set [trial_end](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-trial_end) to `now` to end the trial. |
| Has an active trial offer | [Update the subscription](https://docs.stripe.com/api/subscriptions/update.md) to remove the trial offer. |
| Status `unpaid` | Collect or [void](https://docs.stripe.com/api/invoices/void.md) the outstanding invoice to return the subscription to `active`. |
| Status `paused` | Already paused. |
| Status `incomplete` | Complete the initial payment to move the subscription to `active`. |
| Status `incomplete_expired` or `canceled` | Create a new subscription. |
| Has an attached [schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) | [Release the schedule](https://docs.stripe.com/api/subscription_schedules/release.md). |
| Has an active [billing schedule](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_schedules) | [Update the subscription](https://docs.stripe.com/api/subscriptions/update.md) to clear the billing schedules by passing an empty string for `billing_schedules`. |