# Pause and resume subscriptions on a schedule

Schedule pauses and resume attempts for your customers' subscriptions.

Use a pause schedule to temporarily stop service without canceling the subscription. Schedule a pause for a customer’s vacation, pause immediately and choose when Stripe attempts to resume, or add a resume date to a subscription that’s already paused.

Starting a resume attempt can change the subscription’s status immediately or leave it `paused`. The resume succeeds when the status changes from `paused` to `active` or `past_due`. It can succeed immediately when Stripe doesn’t create an invoice, the invoice requires no payment, or a synchronous payment succeeds.

## Before you begin

- Use [flexible billing mode](https://docs.stripe.com/billing/subscriptions/billing-mode.md) and `charge_automatically` collection for the subscription and every schedule phase.
- Use a [subscription schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md). Pause schedules don’t apply directly to subscriptions. When you create a subscription schedule with `from_subscription`, you can add `pause_schedules` in the same request.

- If you use a restricted API key, grant it `subscription_write`. Invoice previews also require `invoice_read`. See [API permissions](https://docs.stripe.com/keys/permissions-reference.md) and [API key best practices](https://docs.stripe.com/keys-best-practices.md).

## Create a pause schedule

Choose the flow that matches the subscription’s current status and whether you want to schedule a resume:

- [Schedule a future pause and resume](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#schedule-a-future-pause-and-resume).
- [Schedule a future pause without a resume](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#schedule-a-future-pause-without-a-resume).
- [Pause immediately and schedule a resume](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#pause-immediately-and-schedule-a-resume).
- [Schedule a resume for an already-paused subscription](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#schedule-a-resume-for-a-paused-subscription).

### Before you begin 

Pause and resume dates follow these rules:

- Future `pause_at` and `resume_at` timestamps must be strictly after the subscription schedule’s start time. When creating a schedule with `from_subscription`, `pause_at.type: "now"` can equal the schedule’s start time.
- Set pause and resume dates no more than 20 years after the request.
- The resume date must be strictly after the pause date.
- Include `pause` when you create a pause schedule, unless you create it from an already-paused subscription. In that case, omit `pause` or set `pause.pause_at` to the original pause time.
- The subscription can’t be in a trial at `pause_at` or enter a trial while paused.
- With `end_behavior: "cancel"`, both dates must be strictly before the subscription schedule’s end time.
- With `end_behavior: "release"`, either action can occur at the subscription schedule’s end time. Neither date can be after that time.

### Schedule a future pause and resume

Configure `pause_schedules` on a [subscription schedule](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md). Each subscription schedule supports one pause schedule at a time. Its `pause` defines when to pause the subscription, and its optional `resume` defines when to start a resume attempt. The pause and resume attempt have separate settings.

For example, a customer wants Stripe to pause service on December 1 and start a resume attempt on December 31, 2026. Update their existing subscription schedule with both dates. This example assumes the subscription schedule starts with no pause schedule and remains in effect through the resume date:

```curl
curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d "pause_schedules[0][pause][pause_at][type]=timestamp" \
  -d "pause_schedules[0][pause][pause_at][timestamp]=1796083200" \
  -d "pause_schedules[0][resume][resume_at][type]=timestamp" \
  -d "pause_schedules[0][resume][resume_at][timestamp]=1798675200"
```

Replace the subscription schedule ID and timestamps with your own values. Both example timestamps represent 00:00 UTC on their respective dates. Your timestamps must be in the future and meet the [pause schedule requirements](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#before-you-begin). Because the request omits `pause.settings` and `resume.settings`, Stripe uses the [default billing and payment behavior](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#configure-scheduled-resume-behavior). Stripe returns the pause schedule’s `key` in `pause_schedules[0].key`. Save it for future updates.

### Schedule a future pause without a resume

If the customer doesn’t know when they’ll return, omit `resume`. For a subscription without a schedule, create one with `from_subscription`. For example, create a schedule that pauses the subscription on December 1, 2026:

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d from_subscription={{SUBSCRIPTION_ID}} \
  -d "pause_schedules[0][pause][pause_at][type]=timestamp" \
  -d "pause_schedules[0][pause][pause_at][timestamp]=1796083200"
```

When you create a schedule from a subscription, Stripe extends the final phase if necessary to include the pause or resume date. With `end_behavior: "release"`, the schedule detaches from the subscription when the final phase ends.

Without a resume date, Stripe doesn’t start an automatic resume attempt. To add a resume date while the schedule is attached, update the entry’s `resume` and include its existing `key`. If the schedule has already released the subscription, [resume the subscription directly](https://docs.stripe.com/billing/subscriptions/pause.md#resume-a-subscription) or [create a schedule with a resume date](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#schedule-a-resume-for-a-paused-subscription).

### Pause immediately and schedule a resume

For a subscription without an attached schedule, create a schedule to pause immediately and start a resume attempt on a future date. Set `pause.pause_at.type` to `now` and provide a future resume date. To pause immediately without a resume date, omit `resume`. Stripe pauses the subscription as part of this request. If a schedule is already attached, [update that schedule](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#change-a-pause-or-resume-date) instead.

For example, pause a subscription immediately and start a resume attempt on December 1, 2026:

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d from_subscription={{SUBSCRIPTION_ID}} \
  -d "pause_schedules[0][pause][pause_at][type]=now" \
  -d "pause_schedules[0][resume][resume_at][type]=timestamp" \
  -d "pause_schedules[0][resume][resume_at][timestamp]=1796083200" \
  -d "pause_schedules[0][resume][settings][billing_cycle_anchor]=resume_at" \
  -d "pause_schedules[0][resume][settings][payment_behavior]=resume_on_payment_success"
```

You can also express the resume date as a duration from the pause date. For example, use `resume_at: { type: "duration", duration: { interval: "month", interval_count: 1 } }` to start a resume attempt one month after pausing.

### Schedule a resume for a paused subscription 

If the subscription is already paused and has no attached schedule, create a schedule with `from_subscription`. The pause schedule must include `resume`. You can omit `pause` because Stripe uses the subscription’s existing pause time. If you include `pause.pause_at`, it must match that pause time. Don’t provide pause settings for a pause that already happened.

```curl
curl https://api.stripe.com/v1/subscription_schedules \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d from_subscription={{SUBSCRIPTION_ID}} \
  -d "pause_schedules[0][resume][resume_at][type]=timestamp" \
  -d "pause_schedules[0][resume][resume_at][timestamp]=1796083200" \
  -d "pause_schedules[0][resume][settings][billing_cycle_anchor]=resume_at" \
  -d "pause_schedules[0][resume][settings][payment_behavior]=resume_on_payment_success"
```

The resume date must be in the future. To start a resume attempt immediately when no schedule is attached, use the [Resume subscription endpoint](https://docs.stripe.com/billing/subscriptions/pause.md#resume-a-subscription).

## Configure scheduled resume behavior

Use `resume.settings` to control billing and payment when Stripe starts any scheduled resume attempt. If you omit `resume.settings`, Stripe uses the defaults in this section. The examples that set these fields use the default values explicitly.

### Billing cycle anchor defaults

For a pause schedule, `billing_cycle_anchor` defaults to `resume_at`. The [Resume subscription endpoint](https://docs.stripe.com/billing/subscriptions/pause.md#resume-a-subscription) defaults it to the equivalent value `now`. Both values anchor billing when Stripe starts the resume attempt. See [How pausing affects billing](https://docs.stripe.com/billing/subscriptions/pause.md#how-pausing-affects-billing) for pause billing options.

### Payment behavior defaults

For a pause schedule, `payment_behavior` defaults to `resume_on_payment_success`. The Resume subscription endpoint defaults it to `resume_on_payment_attempt`. See [Payment behavior after resuming a subscription](https://docs.stripe.com/billing/subscriptions/pause.md#payment-behavior-after-resuming-a-subscription) for the resulting payment outcomes.

## After you create a pause schedule

For a future pause and resume configured in [Schedule a future pause and resume](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#schedule-a-future-pause-and-resume):

- Scheduling a future pause doesn’t change the subscription’s status. Service and billing continue until the pause date.
- At the pause date, the subscription becomes `paused` and invoice generation stops. Existing invoices continue to advance.
- At the resume date, Stripe starts the resume attempt using your billing and payment settings. The subscription can remain `paused` while it waits for payment. Track the result with the [pause and resume statuses](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#pause-schedule-response).
- Stripe sends `customer.subscription.paused` when the scheduled pause takes effect. It sends `customer.subscription.resumed` when the resume succeeds, not when the resume attempt starts. Scheduling an action doesn’t send either event. Before using events to update service access, [verify webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) and check the subscription’s current `status`. If you use network allowlisting, also use Stripe’s [public IP addresses](https://docs.stripe.com/ips.md).

## Manage a pause schedule

Providing `pause_schedules` replaces the current pause schedule instead of merging it. Include the existing `key` to update the pause schedule and retain parameters that you omit. With no `key` or an unknown `key`, Stripe creates a new pause schedule and discards the existing one, including its settings and status.

### Preview a pause schedule update

A schedule preview returns one next invoice, not a separate simulation for each pause and resume action. Use [Create a preview invoice](https://docs.stripe.com/api/invoices/create_preview.md?api-version=2026-09-30.endive) with `schedule` and `schedule_details.pause_schedules` to preview an update without saving it. For example, preview an earlier resume date before applying it:

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d schedule={{SUBSCRIPTION_SCHEDULE_ID}} \
  -d "schedule_details[pause_schedules][0][key]={{PAUSE_SCHEDULE_KEY}}" \
  -d "schedule_details[pause_schedules][0][resume][resume_at][type]=timestamp" \
  -d "schedule_details[pause_schedules][0][resume][resume_at][timestamp]=1797724800" \
  -d "expand[0]=parent.subscription_details.subscription"
```

The expansion returns the projected subscription at `parent.subscription_details.subscription`. The preview doesn’t change the stored schedule or subscription. Apply the same `pause_schedules` update to the schedule when you’re ready.

Depending on your billing settings, the next invoice can be generated at the pause, when the resume attempt starts, or at the next billing cycle. If you defer pause credits and charges with `pending_invoice_item`, they can appear on that later invoice.

For a paused subscription with no future resume, there’s no upcoming invoice to preview. Include a future resume date in `schedule_details.pause_schedules` to preview billing for the resume attempt and later periods.

### Change a pause or resume date

To edit an entry, [update the subscription schedule](https://docs.stripe.com/api/subscription_schedules/update.md?api-version=2026-09-30.endive) and include the entry’s existing `key`. If the subscription is already paused, leave `pause` out of the update and change only `resume`.

You can edit a resume based on its status:

- With `scheduled` or `error`, you can change the resume date and settings.
- With `pending` or `requires_action`, you can’t edit or remove the resume, or clear or replace the pause schedule. Resolve the resumption invoice first.
- With `succeeded`, you can’t edit or remove the resume. You can clear or replace the pause schedule.

For details about resolving `pending` and `requires_action` resumes, see [Resumption invoices and pending updates](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#resumption-invoices-and-pending-updates).

For example, the customer wants Stripe to start the resume attempt on December 20 instead of December 31. Update the resume date without changing the pause or billing settings:

```curl
curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d "pause_schedules[0][key]={{PAUSE_SCHEDULE_KEY}}" \
  -d "pause_schedules[0][resume][resume_at][type]=timestamp" \
  -d "pause_schedules[0][resume][resume_at][timestamp]=1797724800"
```

Before the pause occurs, you can also update `pause.pause_at`, or change both dates in the same entry. To bring a future pause forward to now while retaining its scheduled resume:

```curl
curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d "pause_schedules[0][key]={{PAUSE_SCHEDULE_KEY}}" \
  -d "pause_schedules[0][pause][pause_at][type]=now"
```

You can’t change the time or billing settings of a pause that already occurred. Changed dates must meet the [pause schedule requirements](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#before-you-begin).

### Remove or replace a pause schedule

To remove a scheduled resume before its attempt starts, send the existing `key` with `resume: ""`. To clear the pause schedule, pass `pause_schedules: ""`. Removing a planned action doesn’t undo a pause that already occurred or resume the subscription.

To schedule another pause, provide a new pause schedule without the existing `key`. You don’t need to wait for the existing actions to finish unless the resume is `pending` or `requires_action`. Resolve the resumption invoice before replacing the pause schedule in either status. The new pause schedule replaces the existing one without changing the subscription’s status.

Stripe runs an action during the replacement request if you set `pause.pause_at.type` or `resume.resume_at.type` to `now`. See [Pause immediately and schedule a resume](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#pause-immediately-and-schedule-a-resume) and [Start a resume attempt immediately](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#resume-immediately).

### Start a resume attempt immediately 

To start a resume attempt for a paused subscription while it still has an attached schedule, update the pause schedule entry with `resume.resume_at.type` set to `now`:

```curl
curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive" \
  -d "pause_schedules[0][key]={{PAUSE_SCHEDULE_KEY}}" \
  -d "pause_schedules[0][resume][resume_at][type]=now" \
  -d "pause_schedules[0][resume][settings][billing_cycle_anchor]=resume_at" \
  -d "pause_schedules[0][resume][settings][proration_behavior]=create_prorations" \
  -d "pause_schedules[0][resume][settings][payment_behavior]=resume_on_payment_success"
```

Stripe starts the resume attempt during the update request. If the attempt doesn’t generate an invoice, the resume succeeds immediately. With `resume_on_payment_success`, the subscription remains paused while the resumption invoice is unresolved. See [Resumption invoices and pending updates](https://docs.stripe.com/billing/subscriptions/pause/schedules.md#resumption-invoices-and-pending-updates) for payment outcomes.

Check the subscription’s status and `pause_schedules[0].resume.status.type` before restoring service access.

After the resume succeeds, you can [release the schedule](https://docs.stripe.com/api/subscription_schedules/release.md) if you no longer need it to manage future phases. Release it in a separate request:

```curl
curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTION_SCHEDULE_ID}}/release \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.endive"
```

## Track scheduled actions 

A subscription schedule response represents `pause_at` and `resume_at` as Unix timestamps. The pause and resume each have a status that tracks that action. These statuses are separate from the subscription’s current `status` and the subscription schedule’s `status`. Check the subscription’s current status when deciding whether to provide service access.

### Pause status

Read `pause_schedules[0].pause.status.type` to track the pause:

| Status | Meaning |
| --- | --- |
| `scheduled` | The pause hasn’t taken effect. The subscription continues in its current status until Stripe applies the pause. |
| `succeeded` | Stripe completed the pause. This status remains `succeeded` after a later successful resume or if payment on the pause invoice fails. |
| `error` | Stripe couldn’t complete the pause. Inspect `pause.status.error.message` and, when present, `pause.status.error.code`. Resolve the cause and check the subscription’s current status before rescheduling the pause. |

### Resume status

If you configured a resume, read `pause_schedules[0].resume.status.type` to track it:

| Status | Meaning and next step |
| --- | --- |
| `scheduled` | The resume attempt is scheduled for `resume_at` and hasn’t started. |
| `pending` | The resume attempt is waiting for payment with `resume_on_payment_success`. The subscription remains `paused`. Inspect the resumption invoice and its payment status: payment might have failed, require customer authentication, or still be processing. |
| `requires_action` | With `resume_on_payment_attempt`, Stripe finalized the resumption invoice but hasn’t attempted payment. The subscription remains `paused` while the invoice awaits payment. Initiate payment of the resumption invoice to continue. |
| `succeeded` | The resume succeeded. The subscription’s status is `active` or `past_due`. With `resume_on_payment_attempt`, a failed payment attempt can change it to `past_due`. Check the subscription and invoice statuses to determine whether payment succeeded. |
| `error` | The resume attempt failed, for example because no payment method was available or the resumption invoice was voided. Inspect `resume.status.error.message` and, when present, `resume.status.error.code`. Check the subscription and invoice before rescheduling the resume. |

### Resumption invoices and pending updates

While the resume status is `pending` or `requires_action`, the subscription has a `pending_update` for the resume and remains paused. Its `latest_invoice` identifies the resumption invoice. The subscription’s billing period doesn’t advance until the pending update takes effect and the resume succeeds.

After a failed payment with `resume_on_payment_success`, Stripe can retry according to your retry settings, or you can pay the resumption invoice manually. The invoice outcome determines what happens next:

- **Paid or manually marked uncollectible**: The resume succeeds and Stripe clears the pending update.
- **Automatically marked uncollectible**: If your retry settings mark the invoice uncollectible after the final payment attempt, the subscription remains paused.
- **Voided**: Stripe discards the pending update, leaves the subscription paused, and changes the resume status to `error`. This also happens when the pending update expires and Stripe voids the invoice.

### Reschedule a failed pause or resume 

After resolving a pause or resume `error`, update the pause schedule using its existing `key` and change the corresponding `pause_at` or `resume_at`. Use `type: "now"` to run the action again immediately, or provide a future timestamp. Changing the execution time resets that status to `scheduled`. Resending the stored timestamp preserves `error`, and changing settings alone returns an error.

If a scheduled pause fails, Stripe also marks its planned resume as `error` with code `subscription_schedule_pause_schedule_resume_skipped_after_pause_error`. Changing only `pause_at` reschedules the pause but leaves the resume in `error`, so it won’t run. To reschedule both actions, update both `pause_at` and `resume_at`.

If an immediate pause or resume request fails validation, the API returns an error without saving the requested changes. This differs from a pause or resume status that changes to `error` when a future action runs. Check the API response before assuming the stored status changed.

## Billing and phase behavior

Pause schedules can coincide with billing cycle renewals and subscription schedule phase transitions.

### Pause at a billing cycle boundary

If `pause_at` is the same timestamp as a billing cycle renewal, Stripe processes the pause first. When the pause succeeds, Stripe doesn’t start the next billing period or charge its recurring fees. For example, setting `pause_at` to a monthly subscription’s renewal timestamp pauses it before the next billing period starts.

The pause can still create an invoice for outstanding metered usage or other amounts from the period that ended, depending on `pause.settings`.

### Use a pause with multiple phases

Phases continue to transition on their configured dates while the subscription is paused. Stripe applies changes to the subscription, such as updating its items and prices.

If you configure `add_invoice_items` on a phase that starts while the subscription is paused, Stripe doesn’t create those invoice items.

#### Pause and resume at phase boundaries

When a pause or resume attempt shares a timestamp with a phase transition, Stripe processes the actions in this order:

| Actions at the same time | Order and billing behavior |
| --- | --- |
| Pause and phase transition | Stripe processes the pause first, then applies the phase transition. If the pause fails, the phase transition still occurs and can bill the subscription. |
| Resume and phase transition | Stripe applies the phase transition first while the subscription is still paused, then starts the resume attempt using the updated subscription. |

If the subscription is paused when a phase transition occurs, the transition doesn’t bill recurring charges or prorations. The pause or resume attempt can still generate an invoice or invoice items according to its own settings.

#### Item periods and invoice items

Subscription item changes while paused follow these rules:

- Existing items keep their current billing periods.
- For any item added while paused, including through a phase transition, `current_period_start` and `current_period_end` both equal the time the subscription paused.
- A phase with `billing_cycle_anchor: "phase_start"` changes the subscription’s billing cycle anchor to the phase’s start. It doesn’t reset or advance the items’ current billing periods to that date.

## Test scheduled pauses

In addition to the [general pause and resume tests](https://docs.stripe.com/billing/subscriptions/pause.md#test-with-test-clocks), use test clocks to advance through scheduled actions. Check both a successful resumption payment and a failed payment that leaves the subscription paused. Confirm that Stripe sends `customer.subscription.paused` when the pause takes effect and `customer.subscription.resumed` when the resume succeeds. Also test these cases:

- A pause at the billing cycle renewal timestamp. Confirm that the subscription pauses without starting the next billing period or charging its recurring fees.
- A phase transition at the pause or resume timestamp. Confirm that the phase’s settings apply in the order described and that the transition doesn’t bill recurring charges or prorations while paused.
- A phase that adds an item or resets the billing cycle anchor during a pause. Confirm that item periods stay at their paused values and that a newly added item’s period starts and ends at the pause time.
- A failed pause that you reschedule along with its planned resume. Confirm that both actions run at their updated times.
- A resumption payment that requires authentication or uses an asynchronous payment method with `resume_on_payment_success`. Confirm that the subscription remains paused while payment is unresolved and the resume succeeds when the payment condition is met.