# Pause subscriptions

Pause a subscription to suspend service delivery and invoice generation.

Pausing a subscription suspends both service delivery and invoice generation. Use it to support customer scenarios like vacations, extended non-use, or temporary holds to prevent churn.

## Pause subscription versus pause payment collection

Pausing a subscription stops both service and billing. The subscription moves to `paused` status, Stripe stops generating invoices, and your customer loses access to the service while the subscription is paused.

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

|  | Servicing is paused (customer loses service access) | Invoicing is paused | Payment collection is paused |
| --- | --- | --- | --- |
| **Pause subscription** | Yes | Yes | Yes |
| **Pause payment collection** | No | No | Yes |

## Pause subscriptions

Pause subscriptions to:

- Control subscription lifecycle without canceling when customers go temporarily inactive.
- Build retention flows or support tooling that needs a true pause state.
- Validate billing, entitlement revocation, and webhook handling for paused windows.

> A subscription can also move to `paused` status when a trial ends without a payment method on file. Stripe triggers this automatically and doesn’t use the Pause subscription endpoint. See [Trial end without a payment method](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment).

You can pause subscriptions with 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. After a subscription is paused:

- The subscription status updates to `paused`.
- Stripe notifies you of the status change through 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.
- Stripe pauses invoice generation until you resume, though existing invoices continue to advance without affecting the paused status.
- The [current_period_end](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items-data-current_period_end) updates to the time when you paused the subscription.
- You can use the [bill_for](https://docs.stripe.com/api/subscriptions/pause.md?api-version=preview#pause_subscription-bill_for) parameter to control billing behavior at pause time, including creating credit prorations for unused licensed time and creating debits for metered usage in the current period. You can invoice immediately or create pending invoice items.
- The customer portal reflects that a subscription is paused, but your subscribers can’t use it to pause subscriptions themselves.

> If you pause a subscription that uses a coupon, the coupon retains its original validity. The coupon duration continues to run while the subscription is paused.

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

#### Dashboard

To pause a subscription in the Dashboard:

1. On the [Subscriptions](https://dashboard.stripe.com/subscriptions) page, find the subscription, click the overflow menu (⋯), and select **Pause subscription**.
2. Configure billing behavior for unused time and outstanding usage.
3. Click **Pause subscription**.

#### API

Pause an active subscription:

```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
```

### 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 would not 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"
```

### Subscription response

When you pause a subscription, the response includes a `status_details` object that provides context about the pause:

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

- `status_details.paused.transitioned_at`: Unix timestamp of when the subscription transitioned to `paused` status.

- `status_details.paused.subscription.type` indicates the reason the subscription paused:

| Value | Meaning |
| --- | --- |
| `pause_requested` | You paused the subscription via the API. |
| `trial_end_without_payment_method` | The trial ended without a payment method on file. |
| `system` | Stripe paused the subscription automatically. |

## Resume subscriptions

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

If resuming doesn’t generate an invoice, the subscription status updates to `active` immediately.

If Stripe generates a resumption invoice:

- Stripe finalizes the resumption invoice immediately.
- The subscription becomes `active` once the invoice is paid or marked uncollectible.
- If you void the resumption invoice, the subscription stays `paused`.

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

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 when resuming.

### Payment behavior

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

The `resume_on_payment_success` value is only available for subscriptions that use [flexible billing mode](https://docs.stripe.com/billing/subscriptions/billing-mode.md).

After the subscription status updates to `active`:

- Invoicing resumes.
- You can optionally reset the billing cycle anchor.
- Stripe notifies you of the status change via the [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), 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 re-provision service access.

#### 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

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
```

### Preview the invoice before resuming

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"
```

## 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`.

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

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

## 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"
}
```

## 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
```