Stripe + Supabase: The Pattern for SaaS Subscriptions in 2026

Consider a two-person team whose Supabase subscriptions table still says "active" for a customer who cancelled three days ago. Stripe billed correctly and the dashboard looks fine, but the database was never told. That's a hypothetical, and it's the failure this pattern prevents. The first action: open your subscriptions table and check whether every column can be recomputed from the last webhook event you received.

A working Stripe Supabase subscription setup has four parts: a Stripe webhook handler that verifies every event, a Postgres table that holds plan state, row-level security policies that gate access by that state, and a customer portal so users manage billing without a UI you build yourself.

How do you keep Stripe subscription state in sync with Supabase?

Write subscription state into a Postgres table from one place only, your webhook handler, and let every other part of the app read that table instead of calling Stripe on each page load.

Stripe's own subscription webhook guide describes the same shape: you store an access-expiration value per customer, Stripe sends events as the subscription changes, and your app acts on them. Two rules from that page matter most. After invoice.paid, retrieve the subscription and confirm its status is active before extending access. When the status becomes canceled or unpaid, revoke access. The Supabase Edge Function webhook example is the reference implementation for the receiving side.

If the portal, the app UI and your RLS policies all read one row, they can't disagree. If each calls Stripe separately, they eventually will, usually during a plan change or a failed payment retry. That's my reasoning, not a Stripe statement.

How do you link a Stripe customer to a Supabase user?

Pass your Supabase user ID when you create the Checkout Session, then read it back in the webhook. Stripe's Checkout Session API describes client_reference_id as a unique string, "a customer ID, a cart ID, or similar", used to "reconcile the session with your internal systems", and it also accepts metadata key-value pairs. Matching by email is the fragile alternative: emails change, and a person can end up with two Stripe customers. That last point is my recommendation.

Should the Stripe webhook run in a Supabase Edge Function or a Next.js Route Handler?

Either works, so choose by where the rest of your backend already runs. Stripe doesn't require a specific runtime, only that you verify the signature against the raw request body and return a 2xx quickly.

Those details come from primary pages. The example's source reads the body with req.text() and verifies with STRIPE_WEBHOOK_SIGNING_SECRET. Supabase's function auth docs say to disable JWT verification for webhooks because providers like Stripe don't send Supabase credentials and sign their own requests, so you verify that signature inside the function. The limits page lists the CPU and wall-clock figures. Stripe's webhook docs add that "Stripe requires the raw body of the request", and any framework that touches the body breaks verification.

If you already run other Supabase Edge Functions, keeping billing there avoids a second serverless environment. If Supabase is mainly your database, a Route Handler is one fewer deploy target.

Why does a plain insert break when Stripe retries a webhook?

Because Stripe can deliver the same event more than once, an insert that passes every manual test will hit a unique-constraint error on a duplicate delivery. Write with upsert instead.

Stripe's docs are explicit under best practices: endpoints "might occasionally receive the same event more than once", and you guard against that by logging processed event IDs. Two more behaviours from the same page shape your schema. In live mode Stripe retries for up to three days with exponential backoff, and it doesn't guarantee delivery in the order events were generated, so a handler that assumes customer.subscription.created arrives first will eventually break.

The practical response, which is my recommendation, has two layers. Upsert the subscription row keyed on the Stripe subscription ID, so a repeated event rewrites the same values. When an event's data is ambiguous or out of order, fetch the current subscription from Stripe and write that, because Stripe's docs say you can retrieve missing objects through the API.

Build the handler in this order:

1. Register the endpoint in Stripe and store its whsec_ signing secret in your environment.
2. Read the raw body, not parsed JSON.
3. Verify the signature before touching the database. On failure, return a 4xx and stop.
4. Switch on the event types you need: customer.subscription.updated, customer.subscription.deleted, invoice.paid, invoice.payment_failed, plus checkout.session.completed if you use Checkout.
5. Upsert the row, keyed on the Stripe subscription ID, and record the event ID.
6. Return 200 immediately. Stripe says to return success before any complex logic that might time out.

Skip step 3 and anyone can POST to your endpoint and flip an account to paid. verify_jwt = false is only safe because the signature check inside the function is mandatory.

Test the duplicate path before launch by replaying a real event. Stripe's docs say the Dashboard's Resend button works for up to 15 days after an event is created, and the Stripe CLI's stripe events resend command works for up to 30 days. Your handler should finish in the same state both times.

Does row-level security slow down subscription checks?

Yes, if a policy calls auth.uid() bare, because Postgres can evaluate it for every row, and wrapping it as (select auth.uid()) lets the planner compute it once per statement.

Supabase's RLS performance guide, read on 2026-09-30, benchmarks the change: one test dropped from 179 ms to 9 ms, about 20x, and a combined is_admin() policy test dropped from 11,000 ms to 10 ms. The guide notes the trick only applies when the result doesn't depend on the row. Supabase's database linter also has a check for it, lint 0003, described as a policy "running its check on every single row instead of once per query". Supabase's RLS docs add advice to index every column your policies filter on.

A plan_tier check on a big table looks fine at ten customers and can turn into a latency cost later. Nothing in a green test suite will say which one you're in, so run the linter. For the multi-tenant side of this, see the Supabase RLS multi-tenant post. Webhook handlers using the service-role key bypass RLS by design, per Supabase's docs, so don't debug RLS errors there.

What changed with thin events?

Stripe now offers thin events, compact notifications where you fetch the details you need, and its migration guide says thin events for API v1 resources are in private preview as of 2026-09-30. Previously they covered only v2 resources. Most subscription flows still run on snapshot events, and the guide advises against running both handlers indefinitely. I'm not quoting a payload-size figure because I couldn't confirm one on Stripe's pages this run.

Should you build your own billing screen?

No, start with the customer portal. Stripe's customer portal docs list updating payment methods, switching or cancelling subscriptions, and downloading invoices. Read its limits before you rely on it: subscriptions with multiple products or usage-based billing can be cancelled but not updated there, a new portal session expires after 5 minutes if the customer doesn't open it, and the portal can't be shown inside an iframe. Write the portal launcher as a server action that creates a session for the stored customer ID, then let your webhook record whatever changed.

What do the case studies show, and what don't they?

None of my projects is a Stripe plus Supabase subscription product, so this pattern is documented, not shipped by me. BookBed is Flutter, Firebase and Stripe. Its case study describes Stripe LIVE mode, webhook handlers, and a cross-tab flow where a BroadcastChannel gives an instant signal and Firestore, written by the webhook, stays authoritative. It's the same problem on a different database. Pizzeria Bestek is React with Supabase, three Edge Functions and Row-Level Security on all tables, so it covers the Supabase half without Stripe.

So which pieces do you need on day one? The webhook handler and the table, with upsert and checkout-time user linking from the start. Plain RLS can come first and get the select wrapper once row counts justify it, and the portal can wait a week. The Supabase and Stripe stack guide and the SaaS MVP stack cover the rest.

Now open the table again. If you replayed your last ten Stripe events against it, would it end in the same state?