Cancel a subscription

When a subscription ends, billing stops and the customer's access is revoked. A single API call keeps both in sync and no Stripe webhooks to handle yourself. Choose to cancel immediately, or disable auto-renew so the customer keeps access until the end of the current billing period.

Cancel immediately

Call POST /api/subscriptions/{id}/cancel. A successful cancellation returns 204 No Content. When cancellation completes, the status updates to canceled, cancelledAt is recorded, metered usage records move from current to final, the Subscription's Plans move to inactive, and a subscription.cancelled event is created, so Entitlement checks fail.

import { Salable } from '@salable/sdk';
const salable = new Salable('your-secret-key');
 
await salable.api.subscriptions.byId('sub_01HXYZ8QF4T2VN6M9KDPWJ3RGA').cancel.post();

const response = await fetch('https://salable.app/api/subscriptions/sub_01HXYZ8QF4T2VN6M9KDPWJ3RGA/cancel', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.SALABLE_SECRET_KEY}`
    }
});

For a Salable Only Subscription, that state is finalised in the same request, so access is revoked as soon as the call returns. For a Stripe-backed Subscription, Salable cancels the Stripe Subscription with immediate invoicing and proration, so the customer is credited for the unused portion of the period, but the 204 only confirms Stripe accepted the cancellation; the local status, Plans, usage, and webhook update when Stripe confirms, so poll GET /api/subscriptions/{id} until status is canceled, or wait for subscription.cancelled, before treating access as revoked.

Perpetual Subscriptions cancel through this same endpoint, but because they have no renewal and no recurring charge, cancelling only sets status to canceled and records cancelledAt; there is nothing to prorate or refund.

Important This cannot be undone. Once the status is canceled, entitlement checks fail for every Grantee attached to the Subscription's Plans, and no endpoint restores it. Billing the customer again means creating a new Subscription.

Cancelling a Subscription does not delete Grantees or Groups from Salable. It only revokes their Entitlement access to the Plans on that Subscription.

Cancel at the end of the period

This allows the customer to keep access until the end of their current subscription period. Entitlements stay active, no refund is issued, and the Subscription expires when the current period ends. When the subscription is expiring at the end of it's current period, it'll return cancelAtPeriodEnd: true. If you want to display the date at which it expires, use expiryDate from the Subscription Plans on the Subscription.

import { Salable } from '@salable/sdk';
const salable = new Salable('your-secret-key');
 
await salable.api.subscriptions.byId('sub_01HXYZ8QF4T2VN6M9KDPWJ3RGA').autoRenew.put({
    queryParameters: {
        status: 'disable'
    }
});

const response = await fetch('https://salable.app/api/subscriptions/sub_01HXYZ8QF4T2VN6M9KDPWJ3RGA/auto-renew?status=disable', {
    method: 'PUT',
    headers: {
        Authorization: `Bearer ${process.env.SALABLE_SECRET_KEY}`
    }
});

To resume renewal before the period closes:

import { Salable } from '@salable/sdk';
const salable = new Salable(process.env.SALABLE_SECRET_KEY);
 
await salable.api.subscriptions.byId('sub_01HXYZ8QF4T2VN6M9KDPWJ3RGA').autoRenew.put({
    queryParameters: {
        status: 'enable'
    }
});

const response = await fetch('https://salable.app/api/subscriptions/sub_01HXYZ8QF4T2VN6M9KDPWJ3RGA/auto-renew?status=enable', {
    method: 'PUT',
    headers: {
        Authorization: `Bearer ${process.env.SALABLE_SECRET_KEY}`
    }
});

Related

• Subscriptions and Billing The full lifecycle: proration behaviour, billing anchors, Perpetual and Salable Only Subscriptions.
• Understanding Entitlements How access is resolved at check time, and which Subscription statuses still grant it.
• Webhooks Reacting to subscription.cancelled in your own application.