Adding Basic Dunning to Your Next.js SaaS
How to keep your main database (Prisma/Supabase) in sync with Stripe subscription status when a user enters past_due state in Next.js App Router.
Executive Summary (TL;DR)
- •Never block access to your app the moment a payment fails. Give 3–5 days of grace (Dunning Window).
- •Use Stripe metadata to link `customerId` to your `User` table in Prisma/Drizzle.
- •Handling dunning requires Cron Jobs. Possible on Vercel, but complex. Dunning LITE offloads it for you.
The Problem: State Sync Between Your DB and Stripe
The most common mistake when building a Next.js SaaS is trusting that your user.subscriptionStatus === 'active'is always in sync with Stripe. When a renewal payment fails in the background, Stripe marks the subscription as past_due, but if you are not listening to the webhook correctly, your user will keep unlimited Premium access in your React app.
Minimal Prisma Schema for Dunning in Next.js
The hasFailedPayment field is key to showing warning banners in your UI without immediately blocking access (dunning window):
model User {
id String @id @default(cuid())
email String @unique
stripeCustomerId String? @unique
subscriptionPlan String @default("FREE")
// 👇 CRUCIAL: Add this field for your UI
hasFailedPayment Boolean @default(false)
}Webhook Handler in Next.js App Router for invoice.payment_failed
When Stripe fires the event, your handler must update hasFailedPayment in your database and trigger the user notification flow. Without this sync, dunning is impossible.
The Solution: Offload Dunning to Dunning LITE
Updating the database is the easy part. The hard part is building the entire UX layer in your Next.js App (modals, red banners, emails with scheduled retries) so the user updates their payment method.
By connecting Dunning LITE, we handle the entire recovery email flow in the background. You only need to focus on building the features your users actually pay you for.