DEV Community

Atlas Whoff
Atlas Whoff

Posted on

SaaS Billing in React Server Components: Stripe + Supabase Without a Single `useEffect`

#stripe #nextjs #react #saas

Stripe billing is one of those features that turns into a mess fast. You end up with billing state in React context, useEffect calls to check subscription status, half the data on the client, the other half on the server, and no clear place to put anything.

React Server Components fix this. Billing state is server state. It belongs on the server.

Here's how I rebuilt the billing layer for a production SaaS using RSC + Stripe Meters + Supabase with zero client-side billing logic.

Architecture 

User hits any page
  → RSC fetches subscription status from Supabase
  → Renders gated UI server-side (no flash, no layout shift)
  → Stripe webhook → Supabase → next request sees updated state
Enter fullscreen mode Exit fullscreen mode

No billing state in React. No polling. No optimistic updates. Just a database that webhooks keep current.

Setup 

npm install stripe @supabase/supabase-js @supabase/ssr
Enter fullscreen mode Exit fullscreen mode

Environment variables:

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
Enter fullscreen mode Exit fullscreen mode

The Supabase Schema 

-- Run in Supabase SQL editor
create table if not exists subscriptions (
  user_id uuid primary key references auth.users(id) on delete cascade,
  stripe_customer_id text unique,
  stripe_subscription_id text unique,
  plan text not null default 'free',  -- 'free' | 'pro' | 'enterprise'
  status text not null default 'active', -- 'active' | 'past_due' | 'canceled'
  current_period_end timestamptz,
  usage_this_period integer not null default 0,
  usage_limit integer not null default 100,
  updated_at timestamptz default now()
);

-- RLS: users can only read their own row
alter table subscriptions enable row level security;
create policy "own" on subscriptions for select using (auth.uid() = user_id);
Enter fullscreen mode Exit fullscreen mode

Stripe Client (Server-Only)

Create lib/stripe.ts:

import Stripe from "stripe";

// This file should never be imported in client components
// Add to .eslintrc: { "no-restricted-imports": ["error", { "patterns": ["@/lib/stripe"] }] }
// when in "use client" files
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-03-31.basil"
});
Enter fullscreen mode Exit fullscreen mode

The Subscription Fetcher

Create lib/subscription.ts:

import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY! // service role for server-side reads
);

export interface Subscription {
  plan: "free" | "pro" | "enterprise";
  status: "active" | "past_due" | "canceled";
  usageThisPeriod: number;
  usageLimit: number;
  currentPeriodEnd: Date | null;
}

export async function getSubscription(userId: string): Promise<Subscription> {
  const { data, error } = await supabase
    .from("subscriptions")
    .select("plan, status, usage_this_period, usage_limit, current_period_end")
    .eq("user_id", userId)
    .single();

  if (error || !data) {
    // Default: free plan, 100 requests/month
    return {
      plan: "free",
      status: "active",
      usageThisPeriod: 0,
      usageLimit: 100,
      currentPeriodEnd: null
    };
  }

  return {
    plan: data.plan,
    status: data.status,
    usageThisPeriod: data.usage_this_period,
    usageLimit: data.usage_limit,
    currentPeriodEnd: data.current_period_end
      ? new Date(data.current_period_end)
      : null
  };
}
Enter fullscreen mode Exit fullscreen mode

Server Component: Billing Dashboard

Create app/dashboard/billing/page.tsx:

import { getSubscription } from "@/lib/subscription";
import { getCurrentUser } from "@/lib/auth"; // your auth helper
import { UpgradeButton } from "./UpgradeButton";

export default async function BillingPage() {
  const user = await getCurrentUser();
  if (!user) return null; // middleware should have redirected

  // This runs on the server — no useEffect, no loading state
  const subscription = await getSubscription(user.id);

  const usagePercent = Math.round(
    (subscription.usageThisPeriod / subscription.usageLimit) * 100
  );

  return (
    <div style={{ maxWidth: 600, padding: "2rem" }}>
      <h1>Billing</h1>

      <div style={{ background: "#f9fafb", borderRadius: 8, padding: "1.5rem", marginBottom: "1.5rem" }}>
        <div style={{ display: "flex", justifyContent: "space-between", marginBottom: "0.5rem" }}>
          <span style={{ fontWeight: 600 }}>Current Plan</span>
          <span style={{
            background: subscription.plan === "pro" ? "#dcfce7" : "#f3f4f6",
            color: subscription.plan === "pro" ? "#166534" : "#374151",
            padding: "0.25rem 0.75rem",
            borderRadius: 99,
            fontSize: 13,
            fontWeight: 600
          }}>
            {subscription.plan.toUpperCase()}
          </span>
        </div>

        {subscription.currentPeriodEnd && (
          <p style={{ fontSize: 14, color: "#6b7280", margin: 0 }}>
            Renews {subscription.currentPeriodEnd.toLocaleDateString()}
          </p>
        )}
      </div>

      <div style={{ marginBottom: "1.5rem" }}>
        <div style={{ display: "flex", justifyContent: "space-between", marginBottom: "0.5rem" }}>
          <span style={{ fontWeight: 500 }}>API Requests This Month</span>
          <span style={{ color: usagePercent > 90 ? "#dc2626" : "#374151" }}>
            {subscription.usageThisPeriod.toLocaleString()} / {subscription.usageLimit.toLocaleString()}
          </span>
        </div>
        <div style={{ background: "#e5e7eb", borderRadius: 99, height: 8 }}>
          <div
            style={{
              width: `${Math.min(usagePercent, 100)}%`,
              background: usagePercent > 90 ? "#dc2626" : "#2563eb",
              height: "100%",
              borderRadius: 99,
              transition: "width 0.3s ease"
            }}
          />
        </div>
      </div>

      {subscription.plan === "free" && (
        <UpgradeButton /> // Client component just for the button click
      )}
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

Notice: no useState, no useEffect, no loading spinner. The page renders with data or it doesn't render at all.

The Stripe Webhook

Create app/api/stripe/webhook/route.ts:

import { stripe } from "@/lib/stripe";
import { createClient } from "@supabase/supabase-js";
import { NextRequest } from "next/server";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

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

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

  switch (event.type) {
    case "customer.subscription.updated":
    case "customer.subscription.deleted": {
      const sub = event.data.object;
      const customerId = typeof sub.customer === "string" ? sub.customer : sub.customer.id;

      await supabase
        .from("subscriptions")
        .update({
          status: sub.status,
          plan: sub.status === "active" ? getPlan(sub) : "free",
          current_period_end: new Date(sub.current_period_end * 1000).toISOString(),
          updated_at: new Date().toISOString()
        })
        .eq("stripe_customer_id", customerId);
      break;
    }

    case "invoice.payment_failed": {
      const invoice = event.data.object;
      const customerId = typeof invoice.customer === "string"
        ? invoice.customer
        : invoice.customer!.toString();

      await supabase
        .from("subscriptions")
        .update({ status: "past_due", updated_at: new Date().toISOString() })
        .eq("stripe_customer_id", customerId);
      break;
    }
  }

  return new Response("ok");
}

function getPlan(sub: { items: { data: Array<{ price: { lookup_key?: string | null } }> } }): string {
  const lookupKey = sub.items.data[0]?.price?.lookup_key;
  if (lookupKey?.includes("enterprise")) return "enterprise";
  if (lookupKey?.includes("pro")) return "pro";
  return "free";
}
Enter fullscreen mode Exit fullscreen mode

Usage Tracking in API Routes

Every API call increments the usage counter atomically:

// lib/usage.ts
export async function incrementUsage(userId: string): Promise<boolean> {
  // Atomic increment + limit check in one query
  const { data, error } = await supabase.rpc("increment_usage_if_allowed", {
    p_user_id: userId
  });

  if (error) throw error;
  return data as boolean; // true = success, false = limit exceeded
}
Enter fullscreen mode Exit fullscreen mode

Add to Supabase:

create or replace function increment_usage_if_allowed(p_user_id uuid)
returns boolean
language plpgsql
as $$
declare
  v_current integer;
  v_limit integer;
begin
  select usage_this_period, usage_limit
  into v_current, v_limit
  from subscriptions
  where user_id = p_user_id
  for update;

  if not found or v_current >= v_limit then
    return false;
  end if;

  update subscriptions
  set usage_this_period = usage_this_period + 1,
      updated_at = now()
  where user_id = p_user_id;

  return true;
end;
$$;
Enter fullscreen mode Exit fullscreen mode

The UpgradeButton Client Component 

"use client";

export function UpgradeButton() {
  const handleUpgrade = async () => {
    const res = await fetch("/api/stripe/checkout", { method: "POST" });
    const { url } = await res.json();
    window.location.href = url;
  };

  return (
    <button
      onClick={handleUpgrade}
      style={{
        padding: "0.75rem 1.5rem",
        background: "#2563eb",
        color: "white",
        border: "none",
        borderRadius: 8,
        cursor: "pointer",
        fontWeight: 600,
        fontSize: 15
      }}
    >
      Upgrade to Pro — $29/month
    </button>
  );
}
Enter fullscreen mode Exit fullscreen mode 
// app/api/stripe/checkout/route.ts
import { stripe } from "@/lib/stripe";
import { getCurrentUser } from "@/lib/auth";

export async function POST() {
  const user = await getCurrentUser();
  if (!user) return new Response("Unauthorized", { status: 401 });

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    payment_method_types: ["card"],
    line_items: [{ price: "price_xxx_pro_monthly", quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing?success=1`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing`,
    metadata: { userId: user.id }
  });

  return Response.json({ url: session.url });
}
Enter fullscreen mode Exit fullscreen mode

Why This Architecture Wins

  1. No billing state leaks into React — subscription status is a server concern
  2. No flash of unpaid content — server component renders gated UI before paint
  3. Atomic usage counting — Postgres handles the increment, no race conditions
  4. Webhook-driven — Stripe tells you when things change, you don't poll

The same pattern powers the billing layer at whoffagents.com — 0 client-side billing state, 0 useEffect calls related to subscriptions.

Need the full production-ready SaaS template with auth, billing, and AI already wired together? whoffagents.com

Top comments (0)