# Pausing and canceling

Source: https://developers.swell.is/backend-api/subscriptions/pausing-and-canceling

A subscription can be paused or canceled immediately, or scheduled to take effect on a future date. Both are driven by updating the subscription, and both distinguish intent from effect: `canceled` and `paused` record the intent, while `active` records whether the subscription is still running.

### Canceling immediately

Set `canceled` to `true` with `cancel_at_end` set to `false`. When neither `cancel_at_end` nor `cancel_at_schedule` is already set on the subscription, sending `canceled` on its own cancels immediately too. The subscription is left with `canceled: true`, `active: false`, and `date_canceled` set to the current time.

**Cancel a subscription immediately**

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: true,
  cancel_at_end: false
});
```

### Scheduling a cancellation

Send `canceled` together with `cancel_at_schedule`, or set the schedule first and confirm with `canceled` in a second request. The subscription is then `canceled: true` and `active: true`, with the calculated date in `date_cancel_at`. It keeps generating orders and invoices until that date, at which point `active` becomes `false` and `date_canceled` is set.

**Schedule a cancellation**

**Node**

```javascript
// Cancel on the next billing date
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: true,
  cancel_at_schedule: 'billing'
});

// Or cancel on a specific date
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: true,
  cancel_at_schedule: '2027-01-31T00:00:00.000Z'
});
```

#### Schedule values

The same values apply to `cancel_at_schedule` and `pause_at_schedule`.

- `billing`: the end of the current billing period, from `date_period_end`. During a trial, `date_trial_end` is used instead.
- `order`: the end of the current order period, from `date_order_period_end`.
- `first`: whichever of the two comes first.
- `last`: whichever of the two comes last.
- An ISO 8601 date string: that exact date.

`first` and `last` both fall back to the billing period when the subscription has no order period. A value that cannot be read as a date, or a date that is not in the future, is ignored and no schedule is set.

### Undoing a cancellation

Setting `canceled` to `false` reverses a cancellation whether it is still scheduled or already complete. A pending cancellation is dropped and `date_cancel_at` is cleared. A subscription that had already been canceled returns to `active: true` with `date_canceled` cleared, `date_uncanceled` set, and a new billing cycle starting immediately. If the most recent payment attempt had failed, it is retried.

**Undo a cancellation**

**Node**

```javascript
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  canceled: false
});
```

### Pausing

Pausing mirrors cancellation. Send `paused: true` with `pause_at_end: false` to pause immediately, which sets `active: false` and records `date_paused`. Send it with `pause_at_schedule` to schedule one, which keeps the subscription active and stores the calculated date in `date_pause_at`. Orders and invoices continue until that date.

Sending `paused: true` with `pause_at_end: true` is treated as `pause_at_schedule: 'first'`.

**Pause a subscription**

**Node**

```javascript
// Pause now
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: true,
  pause_at_end: false
});

// Pause at the end of the current billing period
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: true,
  pause_at_schedule: 'billing'
});
```

### Resuming

Setting `paused` to `false` both cancels a pause that has not taken effect yet, clearing `date_pause_at`, and resumes a subscription that is already paused. Resuming always begins a new billing and ordering period, and an invoice or order is generated at that moment.

A resume can also be dated ahead. Set `date_pause_end` to resume at a specific time, or set `pause_skip_cycles` to resume after a number of cycles. Skipped cycles are counted from the current period end, following the same `pause_at_schedule` the pause used, and the result is stored in `date_pause_end`. A `date_pause_end` you provide takes precedence over `pause_skip_cycles`.

**Resume a subscription**

**Node**

```javascript
// Resume now, or drop a pause that hasn't taken effect
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: false
});

// Resume two cycles after the current period ends
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  paused: false,
  pause_skip_cycles: 2
});

// Resume on a specific date
await swell.put('/subscriptions/{id}', {
  id: '5c15505200c7d14d851e510f',
  date_pause_end: '2027-03-01T00:00:00.000Z'
});
```

### States

| State | canceled / paused | active | Orders and invoices |
| --- | --- | --- | --- |
| Active | false | true | Generated normally |
| Scheduled, waiting | true | true | Continue until the scheduled date |
| Canceled or paused immediately | true | false | Stopped |
| Stopping at period end, waiting | true | true | Stopped |

A subscription with `canceled: true` and `active: true` is therefore not yet finished. Read `active` to tell whether a subscription is still running, and `date_cancel_at` or `date_pause_at` to tell when it will stop.

### Stopping at the end of the current period

Sending `canceled: true` with `cancel_at_end: true`, and no schedule set, stops orders and invoices right away while leaving `active: true` until the billing period ends. Sending `paused: true` with no scheduling fields behaves the same way for pausing. When `cancel_at_schedule` is present it takes precedence over `cancel_at_end`.