The core rule: Stripe is the source of truth, webhooks keep you in sync

Don't mark a user "pro" because they landed on your /success page. People close tabs, cards get declined three days later, and subscriptions renew or cancel without your app being involved. Your database should only change when Stripe tells you something happened, through a webhook.

1. Tables

create table public.customers (
  user_id uuid primary key references auth.users on delete cascade,
  stripe_customer_id text unique not null
);

create table public.subscriptions (
  id text primary key,                -- Stripe subscription id
  user_id uuid references auth.users on delete cascade,
  status text not null,               -- active, trialing, past_due, canceled...
  price_id text not null,
  current_period_end timestamptz,
  cancel_at_period_end boolean default false,
  updated_at timestamptz default now()
);

alter table public.customers enable row level security;
alter table public.subscriptions enable row level security;

create policy "read own sub" on public.subscriptions
  for select using (auth.uid() = user_id);

Notice there are no insert or update policies. Only your webhook, using the service role key on the server, writes to these tables. Users can read their own row, and that's it.

2. One Stripe customer per user

Create the customer lazily the first time someone starts checkout, and store the mapping:

async function getOrCreateCustomer(userId: string, email: string) {
  const { data } = await admin
    .from('customers').select('stripe_customer_id')
    .eq('user_id', userId).maybeSingle()
  if (data) return data.stripe_customer_id

  const customer = await stripe.customers.create({
    email,
    metadata: { supabase_user_id: userId },
  })
  await admin.from('customers')
    .insert({ user_id: userId, stripe_customer_id: customer.id })
  return customer.id
}

Putting supabase_user_id in metadata is cheap insurance: if your mapping table ever gets out of sync, you can rebuild it from Stripe.

3. Checkout from a server action

'use server'
export async function startCheckout(priceId: string) {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) throw new Error('Not signed in')

  const customer = await getOrCreateCustomer(user.id, user.email!)
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    customer,
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/billing?ok=1`,
    cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/pricing`,
    subscription_data: { metadata: { supabase_user_id: user.id } },
  })
  redirect(session.url!)
}

Validate priceId against a server-side allowlist. Otherwise anyone can pass in any price from your Stripe account.

4. The webhook (where most bugs live)

// app/api/stripe/webhook/route.ts
export async function POST(req: Request) {
  const body = await req.text()                 // raw body, NOT req.json()
  const sig = req.headers.get('stripe-signature')!
  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(
      body, sig, process.env.STRIPE_WEBHOOK_SECRET!)
  } catch {
    return new Response('Bad signature', { status: 400 })
  }

  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated':
    case 'customer.subscription.deleted': {
      const sub = event.data.object as Stripe.Subscription
      await upsertSubscription(sub)
      break
    }
  }
  return new Response('ok')
}

The things that bite people:

• Parsing the body. Signature verification needs the raw string. If you call req.json() first, every webhook fails with a signature error.
• Wrong secret. The Stripe CLI (stripe listen) gives you a different whsec_ than the dashboard endpoint. Local and production need different values.
• Out-of-order events. Stripe doesn't guarantee order. Rather than trusting the event payload blindly, re-fetch the subscription (stripe.subscriptions.retrieve(sub.id)) and upsert its current state. Then order doesn't matter.
• Retries. Make the handler idempotent: an upsert keyed on the subscription id is safe to run twice.
• Slow handlers. Return 2xx quickly. If you need to send emails or provision things, queue them.

async function upsertSubscription(s: Stripe.Subscription) {
  const fresh = await stripe.subscriptions.retrieve(s.id)
  const item = fresh.items.data[0]
  await admin.from('subscriptions').upsert({
    id: fresh.id,
    user_id: fresh.metadata.supabase_user_id,
    status: fresh.status,
    price_id: item.price.id,
    current_period_end: new Date(item.current_period_end * 1000).toISOString(),
    cancel_at_period_end: fresh.cancel_at_period_end,
    updated_at: new Date().toISOString(),
  })
}

(Depending on your Stripe API version, current_period_end lives on the subscription or on the item. Check which one your version uses.)

5. Gating features

Wrap the check in one helper and use it everywhere:

export async function hasActivePlan(userId: string) {
  const { data } = await supabase.from('subscriptions')
    .select('status').eq('user_id', userId)
    .in('status', ['active', 'trialing']).maybeSingle()
  return !!data
}

For anything sensitive, enforce it in RLS or on the server too, not only by hiding a button.

6. Let Stripe handle the billing UI

Don't build "change plan / update card / cancel" screens yourself. The Customer Portal does all of it:

const portal = await stripe.billingPortal.sessions.create({
  customer, return_url: `${siteUrl}/billing`,
})

Changes made in the portal come back through the same webhook, so your database stays correct without any extra code.

7. Test before launch

• stripe listen --forward-to localhost:3000/api/stripe/webhook
• stripe trigger customer.subscription.updated
• Test cards for declines and 3D Secure (4000 0025 0000 3155).
• Use test clocks to simulate a renewal and a failed payment.
• Deploy, add the production webhook endpoint in the dashboard, and confirm Vercel's env vars use live keys only in Production.

Summary

Keep Stripe as the source of truth. Let a signed, idempotent webhook write to Supabase with the service role key. Users get read-only access through RLS. And let the Customer Portal do the boring billing screens. Set it up this way once and subscriptions stop being the scary part of launching a SaaS.

I'm Dipak, a full-stack developer building SaaS MVPs with Next.js, Supabase and Stripe. I'm available for freelance work. You can hire me on Fiverr.

Need help with something similar? Portfolio: https://cartcord.com | Discord: rambo0671