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 subscription.updated and subscription.canceled events when the period actually ends.
• webhooks if you haven't set up the webhook endpoint yet.

Don't need your own cancel button? Two alternatives:

• Customer portal deep link. Mint a portal session with paddle.customerPortalSessions.create(customerId, [subscriptionId]) and redirect to session.urls.subscriptions[0].cancelSubscription (see customer-portal). Paddle hosts the cancel UI.
• Paddle Retain cancellation flows. If you've set up cancellation flows in Paddle Retain, launch one from the browser with Paddle.js: paddle.Retain.initCancellationFlow({ subscriptionId }). It shows salvage offers first; if the customer goes ahead, Retain cancels the subscription in Paddle for you. The promise resolves with a status of retained, aborted, chose_to_cancel, or error. Retain isn't available in sandbox, so test this flow in live.

Prerequisites