Supabase + Stripe + Next.js App Router TypeScript Integration

Trying to build a SaaS without proper TypeScript setup? Yeah, that's how you end up refunding someone $2,147 when their plan was supposed to be $21/month. Turns out someone passed cents as an integer instead of the price ID string. TypeScript would've caught that stupid type conversion bug immediately, but we were too clever for types back then.

Anyway, here's the thing about TypeScript in this stack - it helps you model the relationships between all these services without your data getting fucked up between API calls.

Why TypeScript Matters for Payment Integration

Payment processing will ruin your life if you get it wrong. One typo and you're either losing money or overcharging customers. Stripe's TypeScript SDK is decent, but it won't save you from yourself. The Stripe API reference has types, but they're not foolproof. I've seen payment processing best practices guides that completely ignore the edge cases that break at 2am.

Consider this common mistake:

// ❌ This will silently fail and you'll spend 2 hours figuring out
// that you passed "price_free" instead of a real price ID
const createSubscription = async (customerId: string, price: string) => {
  const subscription = await stripe.subscriptions.create({
    customer: customerId,
    items: [{ price }],
  });
  // Ask me how I know this breaks in production
};

Here's what actually works when you need to not bankrupt yourself:

// ✅ Type-safe with proper validation
import { z } from 'zod';

const CreateSubscriptionSchema = z.object({
  customerId: z.string().min(1),
  priceId: z.string().startsWith('price_'),
});

type CreateSubscriptionInput = z.infer<typeof CreateSubscriptionSchema>;

const createSubscription = async (input: CreateSubscriptionInput) => {
  const { customerId, priceId } = CreateSubscriptionSchema.parse(input);
  
  const subscription = await stripe.subscriptions.create({
    customer: customerId,
    items: [{ price: priceId }],
  });
  
  return subscription;
};

Database Type Generation Strategy

Supabase generates TypeScript types from your database schema, which is great until you change a column name and your entire frontend explodes. Your types ARE the contract - mess with the database without regenerating types and you're debugging "Property 'user_id' does not exist" errors on Sunday morning. The Supabase CLI documentation shows local development setup, but the Supabase TypeScript guide glosses over how this breaks in real projects.

Generate types regularly during development:

npx supabase gen types typescript --project-id your-project-id > types/database.types.ts

When this fails (and it fucking will), you'll get some bullshit error like "socket hang up" or "connection refused."

Just run it again. The Supabase CLI is temperamental as hell - sometimes it works, sometimes it doesn't, no one knows why.

Critical pattern - separate generated types from application types:

// types/database.types.ts (generated)
export interface Database {
  public: {
    Tables: {
      users: {
        Row: {
          id: string;
          email: string;
          created_at: string;
        };
        Insert: {
          id?: string;
          email: string;
          created_at?: string;
        };
        Update: {
          id?: string;
          email?: string;
          created_at?: string;
        };
      };
    };
  };
}

// types/application.types.ts (your business logic types)
import { Database } from './database.types';

export type UserRow = Database['public']['Tables']['users']['Row'];
export type CreateUserInput = Database['public']['Tables']['users']['Insert'];

export interface UserProfile extends UserRow {
  subscription_status: 'active' | 'canceled' | 'past_due';
  stripe_customer_id: string;
}

Next.js 15 App Router Integration Patterns

Next.js 15 made Request APIs async, breaking every cookies() and headers() call you've ever written. Now you need await everywhere or your build fails with "cookies is not a function" errors.

The migration broke every auth check I'd written because apparently backwards compatibility is for chumps. Spent a solid day just adding await keywords everywhere like some kind of TypeScript zombie.

The Next.js TypeScript documentation tries to help, but good luck migrating a real app. The App Router documentation assumes you're starting fresh. For auth, the Supabase Next.js Auth guide and middleware docs will get you started, then you'll spend a week fixing edge cases.

Server Components with proper TypeScript:

// app/dashboard/page.tsx
import { createClient } from '@/lib/supabase/server';
import { redirect } from 'next/navigation';

export default async function DashboardPage() {
  const supabase = await createClient();
  
  const {
    data: { user },
    error
  } = await supabase.auth.getUser();

  if (!user || error) {
    redirect('/auth/login');
  }

  // TypeScript knows user exists here
  return <DashboardContent user={user} />;
}

interface DashboardContentProps {
  user: User; // Import from @supabase/supabase-js
}

function DashboardContent({ user }: DashboardContentProps) {
  // Fully typed component
  return <div>Welcome, {user.email}</div>;
}

Server Actions with validation:

// app/actions/subscription.ts
'use server';

import { z } from 'zod';
import { createClient } from '@/lib/supabase/server';
import { redirect } from 'next/navigation';

const UpdateSubscriptionSchema = z.object({
  priceId: z.string().startsWith('price_'),
  customerId: z.string().startsWith('cus_'),
});

export async function updateSubscription(
  prevState: any,
  formData: FormData
) {
  const supabase = await createClient();
  
  const rawData = {
    priceId: formData.get('priceId'),
    customerId: formData.get('customerId'),
  };

  const result = UpdateSubscriptionSchema.safeParse(rawData);
  
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
    };
  }

  try {
    // Type-safe database and Stripe operations
    const { data: user } = await supabase.auth.getUser();
    if (!user.user) {
      redirect('/auth/login');
    }

    const subscription = await stripe.subscriptions.create({
      customer: result.data.customerId,
      items: [{ price: result.data.priceId }],
    });

    // Update database with new subscription
    const { error } = await supabase
      .from('user_subscriptions')
      .upsert({
        user_id: user.user.id,
        stripe_subscription_id: subscription.id,
        status: subscription.status,
        current_period_end: new Date(subscription.current_period_end * 1000),
      });

    if (error) {
      throw error;
    }

    return { success: true };
  } catch (error) {
    return {
      errors: {
        _form: ['Failed to update subscription'],
      },
    };
  }
}

Payment Processing Type Safety

Stripe webhooks are a TypeScript nightmare. Everything comes in as any and you're back to JavaScript-style debugging.

Found this out the hard way when Stripe API version 2023-10-16 changed their subscription object structure - suddenly our webhook handler started throwing "Cannot read property 'current_period_end' of undefined" because they moved it into a nested object. Three hours of debugging later, I realized our validation was based on the old payload format.

Their documentation shows these perfect examples but conveniently skips the part where webhooks arrive out of order, duplicate, or just randomly missing fields. Zod documentation helps validate webhook event types, but you'll still miss edge cases.

Type-safe webhook processing:

// app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers';
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import { z } from 'zod';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Define webhook event schemas
const CustomerSubscriptionUpdatedSchema = z.object({
  id: z.string(),
  object: z.literal('subscription'),
  customer: z.string(),
  status: z.enum(['active', 'canceled', 'incomplete', 'past_due', 'unpaid']),
  current_period_end: z.number(),
  current_period_start: z.number(),
  items: z.object({
    data: z.array(z.object({
      price: z.object({
        id: z.string(),
        unit_amount: z.number(),
      }),
    })),
  }),
});

type SubscriptionUpdated = z.infer<typeof CustomerSubscriptionUpdatedSchema>;

export async function POST(request: NextRequest) {
  const body = await request.text();
  const headersList = await headers();
  const signature = headersList.get('stripe-signature');

  if (!signature) {
    return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
  }

  try {
    const event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    switch (event.type) {
      case 'customer.subscription.updated':
        await handleSubscriptionUpdated(event.data.object);
        break;
      default:
        console.log(`Unhandled event type: ${event.type}`);
    }

    return NextResponse.json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json(
      { error: 'Webhook handler failed' },
      { status: 400 }
    );
  }
}

async function handleSubscriptionUpdated(subscription: any) {
  // Validate the webhook data
  const result = CustomerSubscriptionUpdatedSchema.safeParse(subscription);
  
  if (!result.success) {
    console.error('Invalid subscription data:', result.error);
    return;
  }

  const validatedSubscription = result.data;

  // Type-safe database operations
  const supabase = createServiceRoleClient();
  
  const { error } = await supabase
    .from('user_subscriptions')
    .update({
      status: validatedSubscription.status,
      current_period_end: new Date(validatedSubscription.current_period_end * 1000),
      updated_at: new Date().toISOString(),
    })
    .eq('stripe_subscription_id', validatedSubscription.id);

  if (error) {
    console.error('Database update error:', error);
    throw error;
  }
}

This catches Stripe's bullshit API changes before they cost you money. Way better than finding out from angry customer emails.

Next up: authentication patterns that won't leave you debugging "user is null" errors in production.

OK, personal rant over. Here's how I handle user-customer relationships without losing my mind. I spent three weeks figuring this shit out when my first SaaS launched and customers were getting orphaned Stripe records everywhere.

User-Customer Relationship Modeling

Here's the thing - every user needs exactly one Stripe customer. Fuck this up and you get orphaned records everywhere. I learned this the hard way when a failed webhook left 50 users without billing records and I had to manually reconcile everything.

You need to understand Supabase Auth or you'll be debugging sessions forever. The Row Level Security docs are actually decent, and the Stripe Customer API is straightforward once you stop fighting it. Check out the Supabase database design guide and PostgreSQL foreign keys if you want to do this right.

Your foreign keys are what save your ass when webhooks fail and users delete accounts at the worst possible time.

Database schema with proper TypeScript types:

// Database migrations (run via Supabase CLI)
-- Create users table that extends auth.users
create table public.user_profiles (
  id uuid references auth.users on delete cascade primary key,
  email text not null,
  full_name text,
  avatar_url text,
  stripe_customer_id text unique,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  updated_at timestamp with time zone default timezone('utc'::text, now()) not null
);

-- Create subscriptions table
create table public.user_subscriptions (
  id uuid default gen_random_uuid() primary key,
  user_id uuid references public.user_profiles(id) on delete cascade not null,
  stripe_subscription_id text unique not null,
  stripe_customer_id text not null,
  status text not null check (status in ('active', 'canceled', 'incomplete', 'past_due', 'unpaid', 'trialing')),
  price_id text not null,
  quantity integer not null default 1,
  current_period_start timestamp with time zone not null,
  current_period_end timestamp with time zone not null,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  updated_at timestamp with time zone default timezone('utc'::text, now()) not null
);

-- RLS policies
alter table public.user_profiles enable row level security;
alter table public.user_subscriptions enable row level security;

-- Users can only access their own data
create policy "Users can view own profile" on public.user_profiles
  for select using (auth.uid() = id);

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

create policy "Users can view own subscriptions" on public.user_subscriptions
  for select using (auth.uid() = user_id);

Generated TypeScript types (after running supabase gen types):

// types/database.types.ts
export interface Database {
  public: {
    Tables: {
      user_profiles: {
        Row: {
          id: string;
          email: string;
          full_name: string | null;
          avatar_url: string | null;
          stripe_customer_id: string | null;
          created_at: string;
          updated_at: string;
        };
        Insert: {
          id: string;
          email: string;
          full_name?: string | null;
          avatar_url?: string | null;
          stripe_customer_id?: string | null;
          created_at?: string;
          updated_at?: string;
        };
        Update: {
          id?: string;
          email?: string;
          full_name?: string | null;
          avatar_url?: string | null;
          stripe_customer_id?: string | null;
          updated_at?: string;
        };
      };
      user_subscriptions: {
        Row: {
          id: string;
          user_id: string;
          stripe_subscription_id: string;
          stripe_customer_id: string;
          status: 'active' | 'canceled' | 'incomplete' | 'past_due' | 'unpaid' | 'trialing';
          price_id: string;
          quantity: number;
          current_period_start: string;
          current_period_end: string;
          created_at: string;
          updated_at: string;
        };
        Insert: {
          id?: string;
          user_id: string;
          stripe_subscription_id: string;
          stripe_customer_id: string;
          status: 'active' | 'canceled' | 'incomplete' | 'past_due' | 'unpaid' | 'trialing';
          price_id: string;
          quantity?: number;
          current_period_start: string;
          current_period_end: string;
          created_at?: string;
          updated_at?: string;
        };
        Update: {
          id?: string;
          user_id?: string;
          stripe_subscription_id?: string;
          stripe_customer_id?: string;
          status?: 'active' | 'canceled' | 'incomplete' | 'past_due' | 'unpaid' | 'trialing';
          price_id?: string;
          quantity?: number;
          current_period_start?: string;
          current_period_end?: string;
          updated_at?: string;
        };
      };
    };
  };
}

Type-Safe User Registration Flow

Registration is where everything falls apart if you don't plan for failure. I've seen too many apps create a Supabase user, then fail to create the Stripe customer, leaving users in auth limbo. This registration service has saved my ass multiple times by cleaning up properly when things break.

The Supabase Admin API is solid for user creation, and Stripe's Customer creation is straightforward. You'll want to understand TypeScript error handling patterns and database transactions before you ship this.

Registration service that doesn't abandon users:

// lib/services/user-registration.service.ts
import { createServiceRoleClient } from '@/lib/supabase/service-role';
import { stripe } from '@/lib/stripe';
import { z } from 'zod';

const RegisterUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  fullName: z.string().min(1),
});

type RegisterUserInput = z.infer<typeof RegisterUserSchema>;

interface RegistrationResult {
  success: boolean;
  user?: {
    id: string;
    email: string;
    stripeCustomerId: string;
  };
  error?: string;
}

export async function registerUserWithStripeCustomer(
  input: RegisterUserInput
): Promise<RegistrationResult> {
  const supabase = createServiceRoleClient();
  
  try {
    // Validate input
    const { email, password, fullName } = RegisterUserSchema.parse(input);

    // Step 1: Create Supabase user
    const { data: authData, error: authError } = await supabase.auth.admin.createUser({
      email,
      password,
      email_confirm: true, // Skip email confirmation for demo
    });

    if (authError || !authData.user) {
      return {
        success: false,
        error: `Failed to create user: ${authError?.message}`,
      };
    }

    const userId = authData.user.id;

    try {
      // Step 2: Create Stripe customer
      const stripeCustomer = await stripe.customers.create({
        email,
        name: fullName,
        metadata: {
          supabase_user_id: userId,
        },
      });

      // Step 3: Create user profile with Stripe customer ID
      const { error: profileError } = await supabase
        .from('user_profiles')
        .insert({
          id: userId,
          email,
          full_name: fullName,
          stripe_customer_id: stripeCustomer.id,
        });

      if (profileError) {
        // Cleanup: Delete Stripe customer if profile creation fails
        await stripe.customers.del(stripeCustomer.id);
        throw new Error(`Profile creation failed: ${profileError.message}`);
      }

      return {
        success: true,
        user: {
          id: userId,
          email,
          stripeCustomerId: stripeCustomer.id,
        },
      };

    } catch (stripeError) {
      // Cleanup: Delete Supabase user if Stripe operations fail
      await supabase.auth.admin.deleteUser(userId);
      
      return {
        success: false,
        error: `Stripe integration failed: ${stripeError instanceof Error ? stripeError.message : 'Unknown error'}`,
      };
    }

  } catch (error) {
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Registration failed',
    };
  }
}

Subscription Management with Type Safety

Keeping subscription states in sync between Supabase and Stripe is a pain in the ass, but here's how I handle it without losing data when webhooks show up drunk and out of order.

Supabase realtime is cool for showing users instant updates, but don't trust it for critical state - I've seen webhooks arrive 10 minutes late and in random order. The Stripe Subscriptions API is solid once you understand the subscription lifecycle. Their webhook retry logic will save your ass when your server is down. Supabase realtime is great for UI updates, just don't bet the farm on it.

Subscription service that handles webhook chaos:

// lib/services/subscription.service.ts
import { createServiceRoleClient } from '@/lib/supabase/service-role';
import { stripe } from '@/lib/stripe';
import { Database } from '@/types/database.types';

type SubscriptionRow = Database['public']['Tables']['user_subscriptions']['Row'];
type SubscriptionInsert = Database['public']['Tables']['user_subscriptions']['Insert'];
type SubscriptionUpdate = Database['public']['Tables']['user_subscriptions']['Update'];

export class SubscriptionService {
  private supabase = createServiceRoleClient();

  /**
   * Create a new subscription for a user
   * This method ensures data consistency between Stripe and Supabase
   */
  async createSubscription(
    userId: string,
    priceId: string,
    options: {
      trialPeriodDays?: number;
      coupon?: string;
    } = {}
  ): Promise<SubscriptionRow | null> {
    try {
      // Get user profile with Stripe customer ID
      const { data: profile, error: profileError } = await this.supabase
        .from('user_profiles')
        .select('stripe_customer_id')
        .eq('id', userId)
        .single();

      if (profileError || !profile?.stripe_customer_id) {
        throw new Error('User profile or Stripe customer ID not found');
      }

      // Create subscription in Stripe
      const subscription = await stripe.subscriptions.create({
        customer: profile.stripe_customer_id,
        items: [{ price: priceId }],
        trial_period_days: options.trialPeriodDays,
        coupon: options.coupon,
        payment_behavior: 'default_incomplete',
        payment_settings: {
          save_default_payment_method: 'on_subscription',
        },
        expand: ['latest_invoice.payment_intent'],
      });

      // Store subscription in Supabase
      const subscriptionData: SubscriptionInsert = {
        user_id: userId,
        stripe_subscription_id: subscription.id,
        stripe_customer_id: profile.stripe_customer_id,
        status: subscription.status,
        price_id: priceId,
        quantity: subscription.items.data[0]?.quantity || 1,
        current_period_start: new Date(subscription.current_period_start * 1000).toISOString(),
        current_period_end: new Date(subscription.current_period_end * 1000).toISOString(),
      };

      const { data, error } = await this.supabase
        .from('user_subscriptions')
        .insert(subscriptionData)
        .select()
        .single();

      if (error) {
        // Cleanup: Cancel Stripe subscription if database insert fails
        await stripe.subscriptions.cancel(subscription.id);
        throw error;
      }

      return data;

    } catch (error) {
      console.error('Subscription creation failed:', error);
      return null;
    }
  }

  /**
   * Update subscription from Stripe webhook
   * Handles partial failures and data consistency
   */
  async syncSubscriptionFromWebhook(
    stripeSubscription: Stripe.Subscription
  ): Promise<boolean> {
    try {
      const subscriptionUpdate: SubscriptionUpdate = {
        status: stripeSubscription.status,
        price_id: stripeSubscription.items.data[0]?.price.id,
        quantity: stripeSubscription.items.data[0]?.quantity || 1,
        current_period_start: new Date(stripeSubscription.current_period_start * 1000).toISOString(),
        current_period_end: new Date(stripeSubscription.current_period_end * 1000).toISOString(),
        updated_at: new Date().toISOString(),
      };

      const { error } = await this.supabase
        .from('user_subscriptions')
        .update(subscriptionUpdate)
        .eq('stripe_subscription_id', stripeSubscription.id);

      if (error) {
        console.error('Subscription sync failed:', error);
        return false;
      }

      return true;
    } catch (error) {
      console.error('Webhook sync error:', error);
      return false;
    }
  }

  /**
   * Get user's active subscription with type safety
   */
  async getUserSubscription(userId: string): Promise<SubscriptionRow | null> {
    const { data, error } = await this.supabase
      .from('user_subscriptions')
      .select('*')
      .eq('user_id', userId)
      .eq('status', 'active')
      .order('created_at', { ascending: false })
      .limit(1)
      .single();

    if (error && error.code !== 'PGRST116') {
      console.error('Failed to fetch subscription:', error);
      return null;
    }

    return data;
  }

  /**
   * Check if user has active subscription
   * Useful for middleware and route protection
   */
  async hasActiveSubscription(userId: string): Promise<boolean> {
    const subscription = await this.getUserSubscription(userId);
    return subscription?.status === 'active';
  }
}

// Export singleton instance
export const subscriptionService = new SubscriptionService();

Authentication Middleware with Subscription Checks

Middleware is where you'll spend way too much time optimizing database queries because every request hits this code. I've learned to be paranoid about performance here - one slow query and your app feels like it's running through molasses.

The Next.js middleware docs are actually decent, and Supabase auth helpers handle the heavy lifting. You'll want to understand Edge Runtime limitations and Supabase connection pooling before you deploy this and wonder why everything is slow.

Middleware that doesn't kill your performance:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs';
import { Database } from '@/types/database.types';

export async function middleware(request: NextRequest) {
  const res = NextResponse.next();
  const supabase = createMiddlewareClient<Database>({ req: request, res });

  // Refresh session if expired
  const {
    data: { session },
    error,
  } = await supabase.auth.getSession();

  // Public routes that don't require authentication
  const publicRoutes = ['/auth', '/pricing', '/'];
  const isPublicRoute = publicRoutes.some(route => 
    request.nextUrl.pathname.startsWith(route)
  );

  // Redirect unauthenticated users from protected routes
  if (!session && !isPublicRoute) {
    const redirectUrl = request.nextUrl.clone();
    redirectUrl.pathname = '/auth/login';
    redirectUrl.searchParams.set('redirectedFrom', request.nextUrl.pathname);
    return NextResponse.redirect(redirectUrl);
  }

  // Check subscription for premium routes
  const premiumRoutes = ['/dashboard', '/analytics', '/api/premium'];
  const isPremiumRoute = premiumRoutes.some(route =>
    request.nextUrl.pathname.startsWith(route)
  );

  if (session && isPremiumRoute) {
    // Check subscription status (with caching)
    const { data: subscription } = await supabase
      .from('user_subscriptions')
      .select('status')
      .eq('user_id', session.user.id)
      .eq('status', 'active')
      .single();

    if (!subscription) {
      const redirectUrl = request.nextUrl.clone();
      redirectUrl.pathname = '/pricing';
      redirectUrl.searchParams.set('upgrade', 'required');
      return NextResponse.redirect(redirectUrl);
    }
  }

  return res;
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

This setup has kept my sanity intact through multiple production deployments. Your auth won't randomly break and your subscriptions will actually sync when they're supposed to.