> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/guides/billing/subscriptions/pause-a-subscription/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Pause a subscription

# Pause immediately

Pausing stops all billing activity. No invoices are generated and no payments are collected while the subscription is paused.

#### Dashboard

1. Go to **Billing > Subscriptions** in the sidebar
2. Select the subscription to pause
3. Click **Pause subscription**
4. Choose **Pause immediately**
5. Confirm the action

#### API

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/pause \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "pause_behavior": "pause_immediately"
}'
```

The subscription transitions to **Paused** state. The lifecycle engine stops scheduling billing cycles.

# Pause at period end

Schedule the subscription to pause at the end of the current billing period. The customer continues to be billed through the current period.

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/pause \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "pause_behavior": "pause_at_end"
}'
```

The subscription remains **Active** until the current period ends, then automatically transitions to **Paused**.

# Cancel a scheduled pause

If a subscription has a scheduled pause (`pause_at_end`), you can cancel it before the pause activates. The subscription continues billing normally.

#### API

```bash
curl -X DELETE https://app.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/scheduled-pause \
-H "Authorization: Bearer sk_live_..."
```

#### Python SDK

```python
subscription = client.subscriptions.clear_scheduled_pause(
    account_id="acc_abc123",
    subscription_id="sub_abc123"
)
```

> **Note**
>
> This only applies to subscriptions with a pending `pause_at_end`. For subscriptions that are already **Paused**, use the [resume endpoint](#resume-a-paused-subscription) instead.

# Auto-resume

Configure the subscription to automatically resume after a set time.

## Resume after a number of cycles

Set `pause_for_cycles` to calculate the resume date based on the subscription's billing interval:

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/pause \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "pause_behavior": "pause_immediately",
  "pause_for_cycles": 2
}'
```

A monthly subscription paused for 2 cycles resumes 2 months after the current period end.

## Resume on a specific date

Set `resumption_date` to specify exactly when the subscription should resume:

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/pause \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "pause_behavior": "pause_at_end",
  "resumption_date": "2026-05-01T00:00:00Z"
}'
```

The lifecycle engine schedules the resume automatically. No manual action is needed.

# Billing dates while paused

While a subscription is paused, the billing dates (`current_period_end`, `next_invoice_date`) remain frozen at their pre-pause values. This is expected behavior — no invoices are generated and no timeline adjustments happen during the pause.

The timeline is re-anchored only when the subscription resumes, based on your account's [resume billing behavior](#resume-billing-behavior).

> **Note**
>
> The frozen dates may appear stale in API responses while the subscription is paused. This is normal — the dates will be recalculated when the subscription resumes.

# Resume a paused subscription

Manually resume a paused subscription at any time. Resuming reactivates billing and recalculates the billing timeline.

#### Dashboard

1. Go to **Billing > Subscriptions** in the sidebar
2. Select the paused subscription
3. Click **Resume subscription**
4. Confirm the action

#### API

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/resume \
-H "Authorization: Bearer sk_live_..."
```

## Resume billing behavior

Your account's `resume_billing_behavior` setting controls how billing is calculated when a paused subscription resumes. This setting applies to all subscriptions in the account.

### Reset anchor (default)

With `reset_anchor`, the billing anchor is re-set to the resume date:

1. A new billing period starts from the resume date
2. The customer is charged a full period amount (no catch-up for time paused)
3. The original `current_period_end` is discarded
4. The lifecycle engine schedules the next renewal based on the new anchor

This is the default and recommended behavior for most use cases. Customers are not charged for time the subscription was paused.

### Catch up

With `catch_up`, the original billing anchor is preserved:

1. Catch-up invoices are generated for each billing cycle elapsed during the pause
2. The original billing schedule continues from where it left off
3. Multiple invoices may be created if the subscription was paused for multiple cycles

> **Warning**
>
> After a long pause, `catch_up` can generate a burst of invoices (one per skipped cycle). Consider whether this is appropriate for your business model.

## Configure resume billing behavior

Set the resume billing behavior at the account level:

```bash
curl -X PATCH https://app.paymentkit.com/api/{account_id}/subscription-lifecycle-settings \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "resume_billing_behavior": "reset_anchor"
}'
```

| Value          | Description                                                                     |
| -------------- | ------------------------------------------------------------------------------- |
| `reset_anchor` | Re-anchor billing to the resume date. No catch-up charges. (Default)            |
| `catch_up`     | Preserve the original anchor and generate catch-up invoices for elapsed cycles. |

# Pause options reference

| Field              | Description                                                                    |
| ------------------ | ------------------------------------------------------------------------------ |
| `pause_behavior`   | `pause_immediately` (default) or `pause_at_end`                                |
| `pause_for_cycles` | Number of billing cycles to pause for. Auto-calculates the resume date.        |
| `resumption_date`  | Explicit datetime for auto-resume. Mutually exclusive with `pause_for_cycles`. |

# When to pause vs. cancel

| Scenario                                                       | Action                           |
| -------------------------------------------------------------- | -------------------------------- |
| Customer wants a temporary break (vacation, seasonal business) | **Pause**                        |
| Customer wants to stop service permanently                     | **Cancel**                       |
| Customer disputes charges and needs time to resolve            | **Pause**                        |
| Customer downgrades to a free tier                             | **Cancel** the paid subscription |

> **Tip**
>
> Paused subscriptions retain all their configuration (items, payment methods, discounts). When resumed, billing continues with the same setup.

# Webhook events

| Event                  | Trigger                         |
| ---------------------- | ------------------------------- |
| `subscription.paused`  | Subscription was paused         |
| `subscription.resumed` | Paused subscription was resumed |

> Temporarily suspend billing on a subscription without cancelling it. Configure when to pause and when to automatically resume.