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.

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.

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

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

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.

// 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'
});

The same values apply to cancel_at_schedule and pause_at_schedule.

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.

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.

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

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 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'
});

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 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'
});

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.

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.