Subscriptions

Read and manage the customer's recurring orders. Subscriptions are created during checkout when a billing plan is attached to a cart item; this surface lets you list them, pause / resume them, skip the next renewal, and cancel.

List subscriptions

const r = await client.subscriptions.list()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

for (const sub of r.value) {
  console.log(sub.id, sub.status, sub.next_billing_at)
}

Get a single subscription

const r = await client.subscriptions.get('sub_xxx')
if (!r.ok) return

const sub = r.value // SubscriptionWithDetails
console.log(sub.plan)
console.log(sub.items)
console.log(sub.recent_invoices)

Pause / resume

Pausing freezes future renewals indefinitely; resuming reactivates without re-running checkout.

await client.subscriptions.pause('sub_xxx')
// ...later
await client.subscriptions.resume('sub_xxx')

Skip the next renewal

const r = await client.subscriptions.skipNextRenewal('sub_xxx', {
  idempotencyKey: 'skip-sub_xxx-2026-05', // optional
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.success)

Cancel

Cancellation is terminal; the subscription cannot be resumed. Pass a reason for analytics.

const r = await client.subscriptions.cancel('sub_xxx', 'too_expensive', {
  idempotencyKey: 'cancel-sub_xxx-once', // optional
})

if (!r.ok) {
  // Codes you'll see: SUBSCRIPTION_NOT_FOUND, ALREADY_CANCELLED
  console.error(r.error.code, r.error.message)
}

Method reference

Method	Returns
`list()`	`Result<Subscription[]>`
`get(id)`	`Result<SubscriptionWithDetails>`
`pause(id)`	`Result<{ success: boolean }>`
`resume(id)`	`Result<{ success: boolean }>`
`skipNextRenewal(id, opts?)`	`Result<{ success: boolean }>`
`cancel(id, reason?, opts?)`	`Result<{ success: boolean }>`

Checkout Subscriptions are created at checkout time
Orders Each renewal becomes a new order
Auth Subscriptions require an authenticated customer
Error handling ALREADY_CANCELLED, SUBSCRIPTION_NOT_FOUND