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

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

npm install stripe @supabase/supabase-js @supabase/ssr

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...

-- 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);

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"
});

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
  };
}

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>
  );
}

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";
}

// 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
}

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;
$$;

"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>
  );
}

// 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 });
}