Pause subscriptionsPublic preview

Pause a subscription to suspend service delivery and invoice generation.

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

Before you begin

Review the conditions for when you can’t pause a subscription.
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.

Pause a subscription

You can pause subscriptions with either the API or in the Dashboard. Subscriptions must use flexible billing mode, and the pause subscription endpoint requires API version 2025-06-30.preview or later. The pause takes effect immediately.

To pause a subscription in the Dashboard:

On the Subscriptions page in the Dashboard, find the subscription, click the overflow menu (), and select Pause subscription.
Configure billing behavior for unused time and outstanding usage. To learn about each option, see How pausing affects billing.
Click Pause subscription.

After you pause a subscription

The subscription status changes to paused.
The 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, customer.subscription.updated, and entitlements.active_entitlement_summary.updated webhooks so you can de-provision service access.
The customer portal 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 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.

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:

{
  "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 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 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:

Resume a subscription

To resume a subscription, it must use the charge_automatically 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 parameter to control how Stripe handles payment after you resume the subscription. To learn more, see Payment behavior after resuming a subscription.

To resume a paused subscription in the Dashboard:

On the Subscriptions page, find the paused subscription, click the overflow menu (), and select Resume subscription.
Configure proration and billing cycle anchor settings.
Click Resume subscription.

Warning

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

Use the optional 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 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 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:

Identify pause and resume events

Stripe sends the following events for paused and resumed subscriptions.

Event	Description
customer.subscription.paused	Emitted when a subscription pauses.
customer.subscription.resumed	Emitted when a subscription resumes.
customer.subscription.updated	Emitted when a subscription pauses or resumes.
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):

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

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

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 collection	Update the subscription to use `charge_automatically` collection.
Uses classic billing mode	Migrate to flexible billing mode.
Status `trialing`	Set trial_end to `now` to end the trial.
Has an active trial offer	Update the subscription to remove the trial offer.
Status `unpaid`	Collect or void 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	Release the schedule.
Has an active billing schedule	Update the subscription to clear the billing schedules by passing an empty string for `billing_schedules`.