Billing System Implementation Process Documentation

Feature              | Free  | Pro      | Business
---------------------|-------|----------|----------
Items                | 5     | 100      | Unlimited
Workspaces           | 1     | 3        | Unlimited
API Access           | ❌    | ✅       | ✅
Advanced Analytics   | ❌    | ✅       | ✅
Team Collaboration   | ❌    | ✅       | ✅
Priority Support     | ❌    | Email    | Email + Phone
Custom Integrations  | ❌    | ❌       | ✅

// Server action with auth check
export async function createCheckoutSession(tier: SubscriptionTier) {
  const { userId } = await auth()
  if (!userId) return { success: false, error: ... }

  // Stripe operations
  const session = await stripe.checkout.sessions.create({ ... })

  return { success: true, data: { url: session.url } }
}

// Branded types prevent string confusion
export type SubscriptionTier = "free" | "pro" | "business"
export type SubscriptionStatus = "active" | "canceled" | "past_due" | "trialing"

// Comprehensive subscription interface
export interface Subscription {
  _id: string
  userId: string
  stripeCustomerId: string
  stripeSubscriptionId?: string
  tier: SubscriptionTier
  status: SubscriptionStatus
  currentPeriodStart: number
  currentPeriodEnd: number
  cancelAtPeriodEnd: boolean
  trialEndsAt?: number
}

// Subscriptions table with comprehensive indexing
subscriptions: defineTable({
  userId: v.string(),
  stripeCustomerId: v.string(),
  stripeSubscriptionId: v.optional(v.string()),
  tier: v.union(v.literal("free"), v.literal("pro"), v.literal("business")),
  status: v.union(v.literal("active"), v.literal("canceled"), ...),
  currentPeriodStart: v.number(),
  currentPeriodEnd: v.number(),
  cancelAtPeriodEnd: v.boolean(),
  trialEndsAt: v.optional(v.number()),
})
  .index("by_user", ["userId"])
  .index("by_stripe_customer", ["stripeCustomerId"])
  .index("by_stripe_subscription", ["stripeSubscriptionId"])
  .index("by_tier", ["tier"])
  .index("by_status", ["status"])

// Usage tracking for limits
usage: defineTable({
  userId: v.string(),
  period: v.string(), // "2025-01"
  metrics: v.object({
    items: v.number(),
    workspaces: v.number(),
    apiCalls: v.number(),
    storage: v.number(),
  }),
  resetAt: v.number(),
})
  .index("by_user", ["userId"])
  .index("by_period", ["period"])
  .index("by_user_period", ["userId", "period"])

// Query subscriptions
export const getByUser = query({ ... })
export const getByStripeCustomer = query({ ... })
export const getByStripeSubscription = query({ ... })

// Manage subscriptions
export const create = mutation({ ... })
export const update = mutation({ ... })

// Usage tracking
export const getUsage = query({ ... })
export const updateUsage = mutation({ ... })

// Analytics
export const getStats = query({ ... })

// Core hooks
useSubscription()          // Get current subscription from Clerk metadata
useSubscriptionData()      // Get full subscription from Convex (reactive)
useUsageData()            // Get current usage (reactive)

// Feature checks
useHasFeature(feature)    // Boolean: does user have this feature?
useTierFeatures()         // Get all features for current tier
useCanUpgradeTo(tier)     // Boolean: can user upgrade to this tier?

// Usage checks
useUsageLimit(metric)     // Get limit for items/workspaces
useIsOverLimit(metric)    // Boolean: is user over limit?
useUsagePercentage(metric) // Number: percentage of limit used

// Subscription state
useIsSubscriptionActive() // Boolean: is subscription active?
useDaysUntilRenewal()     // Number: days until next billing

// Get subscription (server-side)
await getSubscription()

// Feature gates (throw if not allowed)
await requireFeature("apiAccess")
await requireTier("pro")
await requireUnderLimit("items", currentCount)

// Feature checks (return boolean)
await checkFeature("advancedAnalytics")
const result = await checkUsageLimit("workspaces", currentCount)

// Utility functions
await getUserFeatures()
await isSubscriptionActive()
await getCurrentTier()

// Every server helper starts with auth check
export async function getSubscription(): Promise<SubscriptionMetadata> {
  const { sessionClaims } = await auth()
  if (!sessionClaims?.publicMetadata) {
    return defaultFreeSubscription
  }
  // ... rest of implementation
}

// Feature gates throw errors (caught by error boundaries)
export async function requireFeature(feature: keyof TierFeatures): Promise<void> {
  const subscription = await getSubscription()
  if (!hasFeature(subscription.tier, feature)) {
    throw new Error(`Feature "${feature}" requires ${getRequiredTier(feature)} plan`)
  }
}

import Stripe from "stripe"

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2025-09-30.clover", // Match installed package version
  typescript: true,
})

export function getStripePublishableKey(): string {
  const key = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  if (!key) {
    throw new Error("NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is required")
  }
  return key
}

export async function createCheckoutSession(
  tier: Exclude<SubscriptionTier, "free">,
  billingPeriod: "monthly" | "annual" = "monthly"
): Promise<SubscriptionActionResult<CheckoutSessionData>>

export async function createBillingPortalSession(): Promise<
  SubscriptionActionResult<BillingPortalSessionData>
>

export async function cancelSubscription(): Promise<SubscriptionActionResult<void>>

export interface SubscriptionActionResult<T = unknown> {
  success: boolean
  data?: T
  error?: {
    code: string
    message: string
  }
}

// Usage in component
const result = await createCheckoutSession("pro")
if (result.success && result.data) {
  window.location.href = result.data.url
} else {
  setError(result.error?.message || "Unknown error")
}

BillingSection
├── CurrentPlanCard (shows active subscription)
│   ├── Plan name and status
│   ├── Renewal date / Days until renewal
│   └── Manage Subscription button → Stripe Portal
│
├── AvailablePlansGrid
│   ├── FreePlanCard (always shown)
│   │   ├── Feature list
│   │   └── Current Plan indicator
│   │
│   ├── ProPlanCard
│   │   ├── Popular badge
│   │   ├── Price toggle (monthly/annual)
│   │   ├── Feature list
│   │   └── Upgrade button
│   │
│   └── BusinessPlanCard
│       ├── Price toggle (monthly/annual)
│       ├── Feature list
│       └── Upgrade button
│
└── Error/Loading States

// Before (error):
const stripeCustomerId = user.publicMetadata?.subscription?.stripeCustomerId

// After (fixed with proper casting):
const metadata = user.publicMetadata as Record<string, unknown> | undefined
const subscriptionMeta = metadata?.subscription as { stripeCustomerId?: string } | undefined
const stripeCustomerId = subscriptionMeta?.stripeCustomerId

types.ts (core types)
  ↓
config.ts (configuration using core types)
  ↓
hooks.ts & server.ts (helper functions using configuration)
  ↓
components & actions (UI and server operations)

User (Clerk)
  ├─ 1:1 → Subscription (Convex)
  │         └─ Indexed by userId, stripeCustomerId, stripeSubscriptionId
  │
  └─ 1:N → Usage (Convex)
            └─ Indexed by userId, period, user_period composite

export async function serverAction(params): Promise<ActionResult<T>> {
  try {
    // 1. Auth check
    const { userId } = await auth()
    if (!userId) {
      return { success: false, error: { code: "unauthorized", message: "..." } }
    }

    // 2. Get user data
    const client = await clerkClient()
    const user = await client.users.getUser(userId)

    // 3. Type-safe metadata access
    const metadata = user.publicMetadata as Record<string, unknown> | undefined
    const subscription = metadata?.subscription as SubscriptionMetadata | undefined

    // 4. Business logic
    const result = await performOperation(...)

    // 5. Success response
    return { success: true, data: result }

  } catch (error) {
    // 6. Error handling
    return {
      success: false,
      error: {
        code: "internal_error",
        message: error instanceof Error ? error.message : "Unknown error"
      }
    }
  }
}

User clicks "Upgrade" button
  ↓
Client calls createCheckoutSession() server action
  ↓
Server creates Stripe Customer (if needed)
  ↓
Server creates Checkout Session with Price ID
  ↓
Server returns session URL
  ↓
Client redirects to Stripe Checkout
  ↓
User completes payment
  ↓
Stripe redirects to success URL
  ↓
Webhook updates subscription (TODO)

User clicks "Manage Subscription"
  ↓
Client calls createBillingPortalSession() server action
  ↓
Server creates Portal Session for existing customer
  ↓
Server returns portal URL
  ↓
Client redirects to Stripe Portal
  ↓
User manages payment methods, cancels, etc.
  ↓
Changes reflected via webhook (TODO)

User clicks "Cancel Subscription"
  ↓
Client shows confirmation dialog
  ↓
Client calls cancelSubscription() server action
  ↓
Server finds active Stripe subscription
  ↓
Server updates subscription to cancel at period end
  ↓
Server returns success
  ↓
UI updates to show "Cancels on [date]"
  ↓
Webhook confirms cancellation (TODO)

// Component automatically re-renders when subscription changes
function MyComponent() {
  const { subscription, isLoading } = useSubscriptionData()

  if (isLoading) return <Skeleton />
  if (!subscription) return <ErrorState />

  return <div>{subscription.tier}</div>
}

// Create subscription (typically in webhook)
const subscriptionId = await ctx.db.insert("subscriptions", {
  userId: "user_xxx",
  stripeCustomerId: "cus_xxx",
  tier: "free",
  status: "active",
  currentPeriodStart: Date.now(),
  currentPeriodEnd: Date.now() + 365 * 24 * 60 * 60 * 1000,
  cancelAtPeriodEnd: false,
})

// Update subscription (typically in webhook)
await ctx.db.patch(subscriptionId, {
  tier: "pro",
  stripeSubscriptionId: "sub_xxx",
  currentPeriodEnd: newPeriodEnd,
})

// After updating Convex subscription
const client = await clerkClient()
await client.users.updateUserMetadata(userId, {
  publicMetadata: {
    subscription: {
      tier: "pro",
      status: "active",
      stripeCustomerId: "cus_xxx",
      features: ["apiAccess", "advancedAnalytics", "teamCollaboration"],
    },
  },
})

SettingsLayout
├── SettingsSidebar (navigation)
│   ├── Account
│   ├── Email Addresses
│   ├── Phone Numbers
│   ├── Security
│   ├── Billing ← NEW
│   └── Danger Zone
│
└── SettingsContent (main area)
    └── BillingSection ← NEW
        ├── Current Plan Card
        └── Available Plans Grid

pnpm dev
# Navigate to http://localhost:3017/profile?section=billing

1. Click "Upgrade" on Pro Monthly ($15/mo)
2. Should redirect to Stripe Checkout
3. Use test card: 4242 4242 4242 4242
4. Any future expiry date
5. Any CVC and ZIP
6. Complete payment
7. Should redirect back to /profile?section=billing&success=true

1. Click toggle to "Annual" on Business card
2. Click "Upgrade" ($790/year)
3. Complete Stripe Checkout with test card
4. Verify redirect and pricing displayed correctly

1. After upgrade, click "Manage Subscription"
2. Should open Stripe Customer Portal
3. Verify can view payment methods
4. Verify can view invoices
5. Verify can cancel subscription

1. In Billing Portal, click "Cancel subscription"
2. Confirm cancellation
3. Return to app
4. Verify shows "Cancels on [date]"

# Stripe Keys (Test Mode)
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx

# Stripe Price IDs
NEXT_PUBLIC_STRIPE_PRO_MONTHLY_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PRO_ANNUAL_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_BUSINESS_MONTHLY_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_BUSINESS_ANNUAL_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxxx

# Stripe Webhook Secret (from Stripe CLI)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3017

# Use live mode keys
STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxxxxxxx

# Use live price IDs
NEXT_PUBLIC_STRIPE_PRO_MONTHLY_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxxx
# ... (rest of price IDs)

# Production webhook secret (from Stripe Dashboard)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx

# Production URL
NEXT_PUBLIC_APP_URL=https://homepage.dev

# Install Stripe CLI
brew install stripe/stripe-cli/stripe  # macOS
# or download from https://stripe.com/docs/stripe-cli

# Login
stripe login

# Forward webhooks to local server
stripe listen --forward-to localhost:3017/api/webhooks/stripe

# Copy the webhook signing secret to .env.local

// app/api/webhooks/stripe/route.ts
import { stripe } from "@/lib/subscription/stripe"
import { headers } from "next/headers"

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

  // Verify webhook signature
  const event = stripe.webhooks.constructEvent(
    body,
    signature,
    process.env.STRIPE_WEBHOOK_SECRET
  )

  // Handle events
  switch (event.type) {
    case "customer.subscription.created":
    case "customer.subscription.updated":
      // Update Convex subscription
      // Update Clerk metadata
      break

    case "customer.subscription.deleted":
      // Set tier to free
      // Update both Convex and Clerk
      break

    case "invoice.payment_failed":
      // Update subscription status
      // Send notification
      break
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 })
}

// Create one-time migration script
// Run once after deployment

import { ConvexHttpClient } from "convex/browser"
import { api } from "@/convex/_generated/api"

async function migrateExistingUsers() {
  // Get all Clerk users
  const client = await clerkClient()
  const users = await client.users.getUserList()

  // For each user without subscription
  for (const user of users.data) {
    const hasSubscription = user.publicMetadata?.subscription
    if (!hasSubscription) {
      // Create free subscription in Convex
      const convex = new ConvexHttpClient(process.env.CONVEX_URL)
      const subscriptionId = await convex.mutation(api.subscriptions.create, {
        userId: user.id,
        stripeCustomerId: `temp_${user.id}`, // Will be replaced on first Stripe interaction
        tier: "free",
      })

      // Update Clerk metadata
      await client.users.updateUserMetadata(user.id, {
        publicMetadata: {
          subscription: {
            tier: "free",
            status: "active",
            stripeCustomerId: `temp_${user.id}`,
            features: [],
          },
        },
      })
    }
  }
}

// app/api/webhooks/stripe/route.ts
// Handle Stripe webhook events to update subscriptions

// app/api/webhooks/clerk/route.ts
// Auto-create free subscriptions for new users

// Implement usage tracking in relevant operations
await incrementUsage(userId, "items", 1)
const usage = await checkUsageLimit(userId, "items")

// Show contextual upgrade prompts when users hit limits
if (itemCount >= limit) {
  return <UpgradePrompt
    feature="items"
    currentTier="free"
    requiredTier="pro"
  />
}

// Show usage progress bars in UI
<UsageIndicator metric="items" current={4} limit={5} />
// "4 of 5 items used"

// Create admin dashboard for subscription metrics
- Total MRR (Monthly Recurring Revenue)
- Churn rate
- Upgrade conversion rates
- Revenue per user
- Popular features

// Track detailed usage patterns
- Which features drive upgrades?
- What usage patterns predict churn?
- Optimal time to show upgrade prompts?

apps/homepage-web/
├── app/
│   └── actions/
│       └── subscription.ts              # Server actions for Stripe
│
├── components/
│   └── profile/
│       ├── ProfileManager.tsx           # Modified: Added billing section
│       ├── types.ts                     # Modified: Added "billing" tab
│       └── sections/
│           └── BillingSection.tsx       # New: Billing UI component
│
├── convex/
│   ├── schema.ts                        # Modified: Added subscriptions & usage
│   └── subscriptions.ts                 # New: Convex queries & mutations
│
└── lib/
    └── subscription/
        ├── types.ts                     # Core type definitions
        ├── config.ts                    # Tier features & pricing
        ├── hooks.ts                     # React hooks for client
        ├── server.ts                    # Server helpers for feature gates
        └── stripe.ts                    # Stripe client initialization

docs/
├── BILLING_SETUP.md                     # Setup guide for developers
└── BILLING_IMPLEMENTATION_PROCESS.md    # This document

// From lib/subscription/types.ts
export type SubscriptionTier = "free" | "pro" | "business"
export type SubscriptionStatus = "active" | "canceled" | "past_due" | "trialing"
export interface Subscription { ... }
export interface SubscriptionMetadata { ... }
export interface TierFeatures { ... }
export interface TierPricing { ... }
export interface Usage { ... }

// From lib/subscription/config.ts
export const TIER_FEATURES: Record<SubscriptionTier, TierFeatures>
export const TIER_PRICING: Record<Exclude<SubscriptionTier, "free">, TierPricing>
export function getTierFeatures(tier: SubscriptionTier): TierFeatures
export function hasFeature(tier: SubscriptionTier, feature: keyof TierFeatures): boolean

// From lib/subscription/hooks.ts
export function useSubscription(): SubscriptionMetadata
export function useHasFeature(feature: keyof TierFeatures): boolean
export function useUsageLimit(metric: "items" | "workspaces"): number

// From lib/subscription/server.ts
export async function requireFeature(feature: keyof TierFeatures): Promise<void>
export async function checkUsageLimit(metric, currentUsage): Promise<UsageCheckResult>

# Development
pnpm dev                          # Start dev server
pnpm typecheck                    # Check TypeScript
pnpm lint                         # Lint code

# Stripe CLI
stripe login                      # Authenticate with Stripe
stripe listen --forward-to localhost:3017/api/webhooks/stripe
stripe trigger customer.subscription.created  # Test webhook

# Testing
# Navigate to: http://localhost:3017/profile?section=billing
# Test card: 4242 4242 4242 4242