Documentation

Subscription & Gating System

A comprehensive guide on managing feature access, plans, and user sessions within your SaaS application.

Plan Hierarchy

Level 0

Free

Basic access for all users.

Level 1

Plus

Standard premium features.

Level 2

Enterprise

Full feature suite for scales.

Hierarchy Logic: The gating system uses a "greater than or equal to" approach. If a feature requires plus (Level 1), users on enterprise (Level 2) will also have access.

Code Integration

Hooks & Utilities

Getting the user's active plan:

import { useActivePlan } from "@/lib/auth-client";

function MyComponent() {
  const { plan, loading, subscription } = useActivePlan();
  
  if (loading) return <div>Checking plan...</div>;
  
  return <div>Current Plan: {plan}</div>;
}

Using the gating helper:

import { useActivePlan, gateWithPlan } from "@/lib/auth-client";

function PremiumFeature() {
  const { plan } = useActivePlan();
  const canAccess = gateWithPlan(plan, "plus");

  if (!canAccess) return <UpgradeBanner />;
  
  return <ProDashboard />;
}

Stripe Webhooks

Webhook Configuration

To keep your database in sync with Stripe, you must set up a webhook endpoint.

1. Create Endpoint

In your Stripe Dashboard, add a new endpoint pointing to:

https://your-domain.com/api/auth/stripe/webhook

* /api/auth is the default path for the auth server.

2. Select Events

Make sure to select at least these events:

checkout.session.completed

customer.subscription.created

customer.subscription.updated

customer.subscription.deleted

3. Set Environment Variable

Save the webhook signing secret provided by Stripe and add it to your .env:

STRIPE_WEBHOOK_SECRET=whsec_...

Key File Locations

Location	Purpose
lib/auth.ts	Better Auth config and server helpers.
lib/auth-client.ts	Client side instance and gating hooks.
app/subscription/page.tsx	Public page for billing management.
components/subscription/Plans.tsx	Pricing table and upgrade logic.
prisma/schema.prisma	Database models for Users & Subscriptions.

Need help with Stripe?

Visit the official Stripe dashboard or Better Auth documentation.

Go to Subscription