Managing Subscription Lifecycle: Upgrades and Cancellations

SaaS users need to upgrade plans, downgrade to cheaper tiers, or cancel their memberships. Let us see how to handle subscription lifecycle events using Paddle backend services.

1. Upgrade and Downgrade Flow

When upgrading from a $15 Basic plan to a $40 Premium plan mid-month, Paddle calculates a Prorated Billing amount:

• The user is credited for unused days on the old plan.
• The customer pays the difference immediately.

To update an active user subscription, send a POST request containing the new price ID using the Paddle SDK:

import { Paddle } from "@paddle/paddle-node-sdk";

// Initialize the backend Node.js SDK
const paddle = new Paddle({
  apiKey: process.env.PADDLE_API_SECRET_KEY as string,
  environment: "sandbox",
});

async function upgradeUserSubscription(subscriptionId: string, newPriceId: string) {
  try {
    const updated = await paddle.subscriptions.update(subscriptionId, {
      items: [
        {
          priceId: newPriceId,
          quantity: 1,
        },
      ],
      prorationBillingMode: "prorated_immediately", // Options: prorated_immediately, full_immediately, prorated_next_billing_period
    });

    console.log("Subscription upgraded successfully! Next billing:", updated.nextBillingAt);
  } catch (err: any) {
    console.error("Subscription update failed:", err.message);
  }
}

2. Terminating or Canceling a Subscription

When a user cancels their subscription, you can choose to:

1. Cancel at Period End: Let them keep premium access until their current paid month expires (default recommendation).
2. Cancel Immediately: Revoke access immediately and process refunds.

async function terminateSubscription(subscriptionId: string) {
  // Scheduled cancelation at next billing date (period end)
  const subscription = await paddle.subscriptions.cancel(subscriptionId, {
    effectiveFrom: "next_billing_period", // Options: immediately, next_billing_period
  });

  console.log("Subscription scheduled for cancellation on:", subscription.scheduledChange?.effectiveAt);
}