***

title: Pause a subscription
subtitle: >-
Temporarily suspend billing on a subscription without cancelling it. Configure
when to pause and when to automatically resume.
-----------------------------------------------

# Pause immediately

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

<Tabs>
  <Tab title="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
  </Tab>

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

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://api.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.

<Tabs>
  <Tab title="API">
    ```bash
    curl -X DELETE https://api.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/scheduled-pause \
    -H "Authorization: Bearer sk_live_..."
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python
    subscription = client.subscriptions.clear_scheduled_pause(
        account_id="acc_abc123",
        subscription_id="sub_abc123"
    )
    ```
  </Tab>
</Tabs>

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

# 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://api.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://api.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.

# Resume a paused subscription

Manually resume a paused subscription at any time. Resuming reactivates billing, creates a prorated invoice for the remaining time in the current period, and advances to the next billing cycle.

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Billing > Subscriptions** in the sidebar
    2. Select the paused subscription
    3. Click **Resume subscription**
    4. Confirm the action
  </Tab>

  <Tab title="API">
    ```bash
    curl -X POST https://api.paymentkit.com/api/{account_id}/subscriptions/{subscription_id}/resume \
    -H "Authorization: Bearer sk_live_..."
    ```
  </Tab>
</Tabs>

When a subscription resumes:

1. A prorated invoice is created covering the period from now until the original period end
2. Payment is attempted on the prorated invoice
3. The billing period advances to the next cycle
4. The lifecycle engine schedules the next renewal

# 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.
</Tip>

# Webhook events

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