paddle-subscription-cancel

Cancel a Paddle subscription from Next.js

When to use this skill

Use this skill when building the "Cancel subscription" button (or equivalent) on the authenticated user's billing or account page. It covers a Next.js 15 (App Router) Server Action that calls paddle.subscriptions.cancel() with the right options, the security checks every cancel action needs, what to do after the cancel succeeds, and the relationship between Paddle's canceled status and a scheduledChange block.

This is the initiating side of subscription cancellation. Pair it with:

• subscription-sync for the receiving side — your webhook handler will get a subscription.updated event reflecting the schedule change, then a subscription.canceled event when the period actually ends.
• webhooks if you haven't set up the webhook endpoint yet.

Prerequisites

• A working Paddle account with at least one active subscription (sandbox is fine).
• Server-side PADDLE_API_KEY available — this action runs in a Server Action, never in the browser.
• A customers table and a subscriptions table mirrored from webhooks (see subscription-sync). You need to know which Paddle customer the authenticated user is, and which subscription they're trying to cancel.
• An auth system. The examples use Supabase, but any session-based auth works.

NEXT_PUBLIC_PADDLE_ENV=sandbox             # or "production"
PADDLE_API_KEY=pdl_sdbx_apikey_...

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...              # or SUPABASE_SECRET_KEY (new opaque sb_secret_*)

How paddle.subscriptions.cancel works

const subscription = await paddle.subscriptions.cancel(subscriptionId, {
  effectiveFrom: "next_billing_period", // or "immediately"
});

effectiveFrom controls when the cancellation takes effect:

Value	Meaning	When to use
next_billing_period	Cancellation is scheduled for the end of the current billing period. The status stays active until then; scheduledChange is set on the subscription.	Default for a generic "Cancel subscription" button — the user paid for the period, let them keep it.
immediately	Cancellation takes effect right now. Paddle prorates a refund for the unused portion.	A different, much rarer flow ("Cancel and refund"). Surprises users if used as the default.