Cancellations

Cancel a subscription now or schedule it for period end, controlling whether the customer keeps access until they have paid for, how the final invoice is settled, and whether any unused time is refunded.

Two cancellation modesAskCopy

Every cancellation answers one question: does access end now or at the end of the period the customer already paid for? VINR models this with a single field rather than two endpoints.

How it worksAskCopy

A subscription tracks the window it has billed for as current_period_start and current_period_end. Cancellation never deletes history — it sets the subscription's status and a canceled_at timestamp, and the behaviour depends on the mode.

Schedule cancellation at period endAskCopy

The customer keeps everything they paid for and is not billed again. This is the default for self-service "cancel my plan" flows.

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const sub = await vinr.subscriptions.update('sub_8Qd1Kf2pLm', {
  cancel_at_period_end: true,
});

console.log(sub.status);              // "active"
console.log(sub.cancel_at_period_end); // true
console.log(sub.current_period_end);   // unix ts — access ends here

To undo a scheduled cancellation while the period is still running:

await vinr.subscriptions.update('sub_8Qd1Kf2pLm', {
  cancel_at_period_end: false,
});

Cancel immediatelyAskCopy

Use this when access must stop at once — fraud, an offboarding, or a downgrade to nothing. By default the time the customer already paid for is forfeited; pass prorate: true to credit the unused portion back.

const canceled = await vinr.subscriptions.cancel('sub_8Qd1Kf2pLm', {
  prorate: true,            // credit unused time to the customer
  invoice_now: true,        // finalize the prorated credit immediately
});

console.log(canceled.status);       // "canceled"
console.log(canceled.canceled_at);  // unix ts of cancellation

curl -X POST https://api.vinr.com/v1/subscriptions/sub_8Qd1Kf2pLm/cancel \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prorate": true, "invoice_now": true }'

Resulting eventsAskCopy

Always gate entitlement revocation on subscription.deleted so a customer who downgrades from a scheduled cancel is not locked out early.

export async function POST(req: Request) {
  const payload = await req.text();
  const signature = req.headers.get('x-vinr-signature') ?? '';
  const event = vinr.webhooks.verify(payload, signature);

  if (event.type === 'subscription.deleted') {
    await revokeAccess(event.data.object.customer); // "cust_..."
  }
  return new Response(null, { status: 200 });
}

Edge casesAskCopy

Next stepsAskCopy