How I wired Stripe subscriptions to Supabase in Next.js 15 (the parts tutorials skip)

#nextjs #supabase #stripe #webdev

Every SaaS needs the same foundation: auth, payments, a database, protected routes. I've built this from scratch too many times. This post covers the parts that actually trip people up — not the happy path, but the edge cases that break production apps.

The three Supabase client problem
Most tutorials show one Supabase client. In a Next.js 15 App Router project you need three:

// lib/supabase/client.ts — browser only (Client Components)
import { createBrowserClient } from "@supabase/ssr";

export function createClient() {
return createBrowserClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);
}
// lib/supabase/server.ts — Server Components + API routes
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
const cookieStore = await cookies();
return createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
cookies: {
getAll() { return cookieStore.getAll(); },
setAll(cookiesToSet) {
try {
cookiesToSet.forEach(({ name, value, options }) =>
cookieStore.set(name, value, options)
);
} catch {}
},
},
}
);
}
// lib/supabase/service.ts — webhooks only (bypasses RLS)
import { createClient } from "@supabase/supabase-js";

export function createServiceClient() {
return createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.SUPABASE_SERVICE_ROLE_KEY!
);
}
Why three? The browser client handles auth state on the client side. The server client reads cookies from the Next.js request context and refreshes sessions. The service client uses the service role key — it bypasses Row Level Security entirely, which is what you need in webhooks where there's no authenticated user.

Using the wrong client in the wrong context causes subtle bugs: sessions that don't persist, RLS errors in webhooks, or auth state that doesn't update after login.

Middleware that actually refreshes sessions
Route protection is easy. Session refresh is the part people miss:

// middleware.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
let supabaseResponse = NextResponse.next({ request });

// This line refreshes the session — don't skip it
const { data: { user } } = await supabase.auth.getUser();

if (!user && request.nextUrl.pathname.startsWith("/dashboard")) {
return NextResponse.redirect(new URL("/login", request.url));
}

if (user && (request.nextUrl.pathname === "/login" ||
request.nextUrl.pathname === "/signup")) {
return NextResponse.redirect(new URL("/dashboard", request.url));
}

return supabaseResponse;
}
The critical part: supabase.auth.getUser() in middleware doesn't just check the session — it also refreshes the access token if it's expired and writes the updated cookie back to the response. Without this call, users get logged out unexpectedly after the token TTL.

The Stripe webhook that actually syncs to Supabase
This is where most implementations fail. The webhook handler needs to:

Verify the signature (not optional)
Handle idempotency — Stripe delivers webhooks at least once, sometimes more
Update the correct tables
// app/api/stripe/webhook/route.ts
import { stripe } from "@/lib/stripe";
import { createServiceClient } from "@/lib/supabase/service";
import type Stripe from "stripe";

export async function POST(request: Request) {
const body = await request.text();
const sig = request.headers.get("stripe-signature");

if (!sig) return new Response("No signature", { status: 400 });

let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(
body,
sig,
process.env.STRIPE_WEBHOOK_SECRET!
);
} catch {
return new Response("Invalid signature", { status: 400 });
}

// Service client — no authenticated user in webhooks
const supabase = createServiceClient();

switch (event.type) {
case "customer.subscription.created":
case "customer.subscription.updated": {
const sub = event.data.object as Stripe.Subscription;
const userId = sub.metadata.supabase_user_id;
if (!userId) break;

  const priceId = sub.items.data[0]?.price.id;
  const tier = priceId === process.env.STRIPE_PRICE_PRO_MONTHLY
    ? "pro"
    : "starter";

  // Update the user's tier and status
  await supabase
    .from("profiles")
    .update({
      subscription_status: sub.status as "active" | "canceled" | "past_due" | "trialing",
      subscription_tier: tier,
    })
    .eq("id", userId);

  // Upsert — not insert — so duplicate webhooks don't error
  await supabase.from("subscriptions").upsert({
    user_id: userId,
    stripe_subscription_id: sub.id,
    stripe_customer_id: sub.customer as string,
    status: sub.status,
    price_id: priceId,
    current_period_start: new Date(sub.current_period_start * 1000).toISOString(),
    current_period_end: new Date(sub.current_period_end * 1000).toISOString(),
  }, { onConflict: "stripe_subscription_id" });
  break;
}

case "customer.subscription.deleted": {
  const sub = event.data.object as Stripe.Subscription;
  const userId = sub.metadata.supabase_user_id;
  if (!userId) break;
  await supabase
    .from("profiles")
    .update({ subscription_status: "canceled", subscription_tier: "free" })
    .eq("id", userId);
  break;
}

}

return Response.json({ received: true });
}
Two things to note:

upsert not insert: Stripe guarantees at-least-once delivery. If you use insert, the second delivery throws a unique constraint error. upsert with onConflict handles duplicates cleanly.

supabase_user_id in metadata: When creating the checkout session, pass the user's ID in the subscription metadata. This is how you link a Stripe subscription back to a Supabase user — don't rely on email matching, it's fragile.

// In your checkout route — set the metadata at creation time
const session = await stripe.checkout.sessions.create({
customer: customerId,
mode: "subscription",
line_items: [{ price: priceId, quantity: 1 }],
subscription_data: {
metadata: { supabase_user_id: user.id } // ← this is the link
},
success_url: ${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing?success=true,
cancel_url: ${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing,
});
Database schema: auto-profile on signup
The cleanest pattern: a Postgres trigger that creates the profile row the moment a user signs up, so you never have to handle the "profile doesn't exist yet" case in your app code.

-- Auto-create profile on signup
create or replace function public.handle_new_user()
returns trigger as $$
begin
insert into public.profiles (id, email, full_name, avatar_url)
values (
new.id,
new.email,
new.raw_user_meta_data->>'full_name',
new.raw_user_meta_data->>'avatar_url'
);
return new;
end;
$$ language plpgsql security definer;

create trigger on_auth_user_created
after insert on auth.users
for each row execute procedure public.handle_new_user();
security definer is required here — the trigger runs with the permissions of the function owner (postgres), not the calling user. Without it, the insert into public.profiles fails because the new user doesn't have permission to insert their own row yet (RLS hasn't been evaluated in time).

RLS: the minimum you need
alter table public.profiles enable row level security;
alter table public.subscriptions enable row level security;

-- Users can only read and update their own profile
create policy "Users can view own profile" on public.profiles
for select using (auth.uid() = id);

create policy "Users can update own profile" on public.profiles
for update using (auth.uid() = id);

-- Users can only read their own subscriptions
create policy "Users can view own subscriptions" on public.subscriptions
for select using (auth.uid() = user_id);
No insert policy on profiles — the trigger handles that with security definer. No delete policy — users shouldn't delete their own profile from the app. The webhook uses the service client which bypasses RLS entirely.

Wrapping up
These are the patterns that took me the longest to get right:

Three Supabase clients for different contexts
Middleware that refreshes sessions, not just checks them
Idempotent webhook handler with upsert
Subscription metadata linking Stripe to Supabase
security definer trigger for auto-profile creation
I packaged all of this (plus a dashboard, landing page, and billing page) into a boilerplate called ShipNext: https://dinizjo.gumroad.com/l/xodcmf

Pay what you want for the next 48h. MIT license, 27 files, README gets you deployed on Vercel in ~30 minutes.

Questions about any of the patterns above — happy to go deeper in the comments.