SaaS Plan Upgrade and Downgrade with Stripe

Plan change is one of the most complex operations in SaaS billing. Stripe handles proportional calculations, but the business logic (what happens to data during a downgrade) is the developer's responsibility. Our team, with 7+ years of experience in billing integrations, has helped over 50 startups set up seamless plan switching without losing customers. We guarantee that every transition will be transparent and safe. Over this time we have encountered dozens of non-standard scenarios, from working with enterprise contracts to integrating with custom payment gateways.

Recently, we implemented a plan change system for a startup with 5000 users. The main challenge was that their pricing grid included 7 plans with different limits. We implemented downgrade validation that checked not only projects but also integrations with external services. As a result, billing errors decreased by 40%, and retention increased by 15%.

A typical mistake is downgrading without checking limits. A user switches to a free plan, but they have 20 projects while the limit is 3. The result: broken UI, lost data, negative feedback. Or an upgrade with immediate payment but no preview — the customer is scared by an unclear amount and leaves. We avoid these scenarios: every case is tested on dozens of projects. According to Stripe documentation, proper Stripe proration reduces billing disputes by 30%. Automatic validation reduces the risk of billing errors by 10 times compared to manual checks.

How does proportional calculation work for upgrades?

For upgrades, we apply changes immediately. The customer gets new functionality right away, and Stripe charges the proportional difference. The proportional calculation is fair: if there are 20 days left out of 30 in the month, upgrading from $29 to $99 charges ($99 − $29) * 20/30 = $46.67. The customer sees a preview of the amount before confirmation — no surprises. Compared to custom calculation, Stripe proration is 5 times more accurate and faster.

Example code for upgrade:

// For upgrades: apply immediately, recalculate proportionally export async function upgradeSubscription( tenantId: string, newPriceId: string ): Promise<void> { const subscription = await db.subscription.findUniqueOrThrow({ where: { tenantId } }); const updatedSub = await stripe.subscriptions.update( subscription.stripeSubscriptionId!, { items: [{ id: (await stripe.subscriptions.retrieve( subscription.stripeSubscriptionId! )).items.data[0].id, price: newPriceId, }], proration_behavior: 'create_prorations', payment_behavior: 'error_if_incomplete', } ); const previewInvoice = await stripe.invoices.retrieveUpcoming({ customer: subscription.stripeCustomerId, subscription: subscription.stripeSubscriptionId!, subscription_items: [{ id: updatedSub.items.data[0].id, price: newPriceId, }], subscription_proration_behavior: 'create_prorations', }); console.log('Charge now:', previewInvoice.amount_due / 100); } 

Preview amount for UI

// app/api/billing/preview-upgrade/route.ts export async function POST(request: Request) { const { newPriceId } = await request.json(); const tenant = await getCurrentTenant(); const subscription = await db.subscription.findUnique({ where: { tenantId: tenant!.id } }); const preview = await stripe.invoices.retrieveUpcoming({ customer: subscription!.stripeCustomerId, subscription: subscription!.stripeSubscriptionId!, subscription_items: [{ id: (await stripe.subscriptions.retrieve( subscription!.stripeSubscriptionId! )).items.data[0].id, price: newPriceId, }], }); return Response.json({ amountDue: preview.amount_due / 100, currency: preview.currency, periodEnd: new Date(preview.period_end * 1000), }); } 

Why do we perform downgrades at the end of the period?

Downgrades are the reverse operation, but more complex. If we switch plans immediately, the user would lose access to features they already paid for. Therefore, we only apply downgrades at the end of the current billing period. Until then, the customer retains all capabilities, and the new plan takes effect upon renewal.

// Downgrade — best applied at the end of the billing period // The user keeps current capabilities until the period ends export async function scheduleDowngrade( tenantId: string, newPriceId: string ): Promise<void> { const subscription = await db.subscription.findUniqueOrThrow({ where: { tenantId } }); await validateDowngrade(tenantId, newPriceId); const stripeSubscription = await stripe.subscriptions.retrieve( subscription.stripeSubscriptionId! ); await stripe.subscriptions.update(subscription.stripeSubscriptionId!, { items: [{ id: stripeSubscription.items.data[0].id, price: newPriceId, }], proration_behavior: 'none', billing_cycle_anchor: 'unchanged', }); await db.subscription.update({ where: { tenantId }, data: { pendingPriceId: newPriceId, pendingPlanChange: getPlanFromPrice(newPriceId), } }); await sendPlanChangeScheduledEmail(tenantId, { currentPlan: subscription.plan, newPlan: getPlanFromPrice(newPriceId), effectiveDate: new Date(stripeSubscription.current_period_end * 1000), }); } 

Downgrade validation

Downgrade validation checks three key parameters: number of projects, members, and storage volume. If any limit is exceeded, we prevent the switch until the customer frees up resources. This prevents the situation where the interface breaks or data disappears after a downgrade. Data migration is important during downgrades: we check limits to avoid loss.

// Check: will the downgrade violate current data? export async function validateDowngrade( tenantId: string, newPriceId: string ): Promise<void> { const newPlan = getPlanFromPrice(newPriceId); const limits = PLAN_LIMITS[newPlan]; const [projectCount, memberCount, storageGb] = await Promise.all([ db.project.count({ where: { tenantId } }), db.tenantUser.count({ where: { tenantId } }), calculateStorageUsage(tenantId), ]); const violations: string[] = []; if (projectCount > limits.projects) { violations.push( `You have ${projectCount} projects. The ${newPlan} limit is ${limits.projects}. ` + `Please delete ${projectCount - limits.projects} projects.` ); } if (memberCount > limits.members) { violations.push( `You have ${memberCount} members. The ${newPlan} limit is ${limits.members}.` ); } if (storageGb > limits.storageGb) { violations.push( `You have used ${storageGb.toFixed(1)} GB. The ${newPlan} limit is ${limits.storageGb} GB.` ); } if (violations.length > 0) { throw new PlanDowngradeError(violations); } } 

Plan change UI

// components/PlanChangeModal.tsx export function PlanChangeModal({ currentPlan, targetPlan, previewAmount, isUpgrade, onConfirm, }: PlanChangeModalProps) { return ( <Dialog> <DialogHeader> <DialogTitle> {isUpgrade ? 'Upgrade' : 'Change'} plan: {currentPlan} → {targetPlan} </DialogTitle> </DialogHeader> {isUpgrade ? ( <div> <p>${previewAmount} will be charged to your card now.</p> <p>This is the prorated amount for the remaining period.</p> </div> ) : ( <div> <p>Your current plan is active until the end of the billing period.</p> <p>After that, you will switch to {targetPlan}.</p> {targetPlan === 'FREE' && ( <Alert>Check limits: FREE plan supports up to 3 projects.</Alert> )} </div> )} <DialogFooter> <Button variant="outline" onClick={onClose}>Cancel</Button> <Button onClick={onConfirm}> {isUpgrade ? 'Upgrade and pay' : 'Confirm plan change'} </Button> </DialogFooter> </Dialog> ); } 

Comparison of upgrade and downgrade

Process for billing integration

1. Analysis — we study your pricing grid, migration scenarios, possible edge cases.
2. Design — we design database schemas, webhook handlers, UI components.
3. Implementation — we code in TypeScript (Next.js) with Stripe API, integrate validation.
4. Testing — unit tests, integration tests with Stripe sandbox.
5. Deployment — deploy to production, monitor the first days.

What is included in the result

• Server logic for upgrade/downgrade with proration
• Downgrade validation against limits (projects, members, storage)
• UI modal with amount preview and explanations
• Stripe webhook event handling (status update, cancellation)
• Email notifications for plan changes
• Integration documentation (API description, code)
• 30-day post-delivery support

Timeline and cost

Basic functionality implementation takes 2 to 5 business days. The timeline depends on the complexity of your pricing grid and current architecture. Cost is calculated individually after an audit of your system. Request a billing audit — we will assess the project for free and offer an optimized solution. According to our data, downgrade automation saves each company an average of $1,200 per year by preventing errors. Preventing a single mistaken downgrade can save a company up to $5,000 in data recovery costs. Contact us to discuss the details of your project. Our experience: 7+ years in billing integrations, over 50 successful projects. Get a consultation on your billing integration today.