Pause subscriptionsPublic preview

Pausing a subscription lets you temporarily suspend both service delivery and invoice generation. The ability to pause a subscription helps you support customer scenarios such as vacations, temporary non‑usage, or goodwill pauses 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 subscription’s service for the duration of the pause.

If you want to keep your customer’s access to the service active but temporarily stop collecting payment, use pause payment collection instead.

To pause a subscription, it must use flexible billing mode.

The ability to pause subscriptions is useful for:

• Merchant teams that want API control over subscription lifecycle without canceling subscriptions.
• Backend engineers building retention flows or support tooling that needs a true pause state.
• Developers validating billing, entitlement revocation, and webhook handling for paused windows.

Pause subscriptions

You can pause subscriptions with the API or in the Dashboard. The pause takes effect immediately. After a subscription is paused:

• The subscription status updates to paused.
• You get notified about the status change via the customer.subscription.paused, customer.subscription.updated, and entitlements.active_entitlement_summary.updated webhooks, enabling you to de-provision service delivery accordingly.
• Invoice generation is paused for the entire pause duration, though existing subscription invoices advance without affecting the paused status.
• The current_period_end updates to the time when you paused the subscription.
• You can use the 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.

You can’t pause a subscription if it:

• Uses send_invoice collection
• Uses billing mode classic
• Is in a trial period, or has an active trial offer
• Has paused, incomplete, incomplete_expired, or canceled status
• Has an attached schedule
• Has an attached cadence

Similarly, you can’t attach a schedule or cadence to a paused subscription.

If you pause a subscription that uses a coupon, the coupon retains its original validity and the pause doesn’t extend its duration.

The customer portal reflects that a subscription is paused, but your subscribers can’t use it to pause subscriptions themselves.

Subscription response

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

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

Resume subscriptions

Resume is only available on subscriptions that use charge_automatically 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.
• Stripe doesn’t attempt payment in the resume response. Collect payment using the Pay invoice endpoint.
• When the invoice is paid or marked uncollectible, the subscription becomes active.
• If a payment attempt fails, the subscription becomes past_due.
• If you void the resumption invoice before a payment attempt, the subscription stays paused.
• If there’s not a successful payment within 23 hours, Stripe voids the invoice and the subscription stays paused.

After a subscription’s status updates to active:

• Invoicing resumes.
• The billing cycle anchor is optionally reset.
• You get notified about the status change via the customer.subscription.resumed, customer.subscription.updated, and entitlements.active_entitlement_summary.updated webhooks, enabling you to re-provision service delivery accordingly.

Payment behavior

The payment_behavior parameter is optional. If you omit it, Stripe uses resume_on_payment_attempt, which matches the behavior in the section above. resume_on_payment_success is only available for subscriptions that use flexible billing mode.

Identify pause and resume events

Stripe sends the following events for paused and resumed subscriptions.

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

Query paused subscriptions in Sigma

The subscriptions table in Sigma includes a status column and a status_details JSON column that you can use to identify and analyze paused subscriptions.

Use the following query to find all currently paused subscriptions along with the pause reason and when the pause occurred:

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