Update a Paddle subscription's plan from Next.js

When to use this skill

Use this skill when building "Upgrade plan," "Switch tier," or "Change subscription" actions in your authenticated user's billing UI. It covers a Next.js 15 (App Router) Server Action that calls paddle.subscriptions.update(), the four prorationBillingMode choices and when to pick each, the replace not append semantics of the items array, and the security checks every plan-change action needs.

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

• subscription-sync — your webhook handler will get a subscription.updated event after the change. Your DB mirror picks up the new plan, status, and pricing.
• subscription-cancel — same auth/ownership shape; if you're building both, share the helpers.

Prerequisites

• A Paddle account with at least two prices the user can switch between (e.g. monthly Starter and monthly Pro). Sandbox is fine.
• Server-side PADDLE_API_KEY available — Server Action only.
• Customer + subscription state mirrored from webhooks (see subscription-sync).
• An auth system. Examples use Supabase.