Customer Billing Dashboard

Project Overview

Building a customer-facing billing dashboard that allows users to manage every aspect of their subscription lifecycle. The dashboard integrates directly with Stripe as the source of truth for billing state and exposes a clean, responsive UI for self-service account management.

Tech Stack

• Framework: Next.js 14 (App Router) + TypeScript
• Styling: Tailwind CSS 3.4
• ORM: Prisma 5 with PostgreSQL
• Payments: Stripe API (Node SDK v14)
• Charts: Recharts 2.x for usage analytics
• Auth: NextAuth.js v5 with session-based billing scoping

User Stories

1. As a customer, I can view my current subscription plan, billing cycle, and next invoice date
2. As a customer, I can browse and filter my invoice history and download PDF receipts
3. As a customer, I can upgrade or downgrade my plan and preview proration charges before confirming
4. As a customer, I can add, remove, and set a default payment method using Stripe Elements
5. As a customer, I can view my API usage, storage consumption, and seat utilization with daily/weekly/monthly charts
6. As a customer, I receive email notifications for upcoming invoices, failed payments, and plan changes

Architecture Plan

File structure follows Next.js App Router conventions with co-located components and a clean separation between API routes, UI components, and shared utilities.

src/
  app/
    (dashboard)/
      billing/
        page.tsx                  # Main billing overview
        invoices/
          page.tsx                # Invoice history list
          [id]/page.tsx           # Invoice detail + PDF download
        subscription/
          page.tsx                # Current plan + upgrade/downgrade
        payment-methods/
          page.tsx                # Saved cards, add new
        usage/
          page.tsx                # Usage charts + quotas
    api/
      billing/
        invoices/route.ts         # GET invoices from Stripe
        subscription/route.ts     # CRUD subscription
        payment/route.ts          # Payment method management
        webhook/route.ts          # Stripe webhook handler
  components/
    billing/
      InvoiceTable.tsx            # Sortable, filterable invoice list
      PlanCard.tsx                # Current plan display + CTA
      UsageChart.tsx              # Recharts usage visualization
      PaymentMethodCard.tsx       # Card display with delete/default
      BillingAlert.tsx            # Overdue, expiring, limit warnings
  lib/
    stripe.ts                     # Stripe client singleton
    billing-utils.ts              # Format currency, dates, plan names
  types/
    billing.ts                    # TypeScript interfaces

Implementation Phases

Key Technical Decisions

Data Model

Prisma schema with PostgreSQL. The local database mirrors Stripe state received through webhooks and adds application-specific fields like usage tracking.

model Customer {
  id                String         @id @default(uuid())
  email             String         @unique
  name              String?
  stripeCustomerId  String         @unique @map("stripe_customer_id")
  createdAt         DateTime       @default(now())
  updatedAt         DateTime       @updatedAt

  subscriptions     Subscription[]
  invoices          Invoice[]
  usageRecords      UsageRecord[]

  @@map("customers")
}

model Subscription {
  id                    String    @id @default(uuid())
  stripeSubscriptionId  String    @unique @map("stripe_subscription_id")
  customerId            String    @map("customer_id")
  status                String    // active, past_due, canceled, trialing
  planId                String    @map("plan_id")
  planName              String    @map("plan_name")
  currentPeriodStart    DateTime  @map("current_period_start")
  currentPeriodEnd      DateTime  @map("current_period_end")
  cancelAtPeriodEnd     Boolean   @default(false) @map("cancel_at_period_end")
  createdAt             DateTime  @default(now())
  updatedAt             DateTime  @updatedAt

  customer              Customer  @relation(fields: [customerId], references: [id])

  @@map("subscriptions")
}

model Invoice {
  id                String    @id @default(uuid())
  stripeInvoiceId   String    @unique @map("stripe_invoice_id")
  customerId        String    @map("customer_id")
  amountDue         Int       @map("amount_due")       // in cents
  amountPaid        Int       @map("amount_paid")      // in cents
  currency          String    @default("usd")
  status            String    // draft, open, paid, void, uncollectible
  invoiceUrl        String?   @map("invoice_url")
  pdfUrl            String?   @map("pdf_url")
  periodStart       DateTime  @map("period_start")
  periodEnd         DateTime  @map("period_end")
  createdAt         DateTime  @default(now())

  customer          Customer  @relation(fields: [customerId], references: [id])

  @@map("invoices")
}

model UsageRecord {
  id          String    @id @default(uuid())
  customerId  String    @map("customer_id")
  metric      String    // api_calls, storage_bytes, seats
  quantity    BigInt
  timestamp   DateTime  @default(now())

  customer    Customer  @relation(fields: [customerId], references: [id])

  @@index([customerId, metric, timestamp])
  @@map("usage_records")
}

API Endpoints

Method	Path	Description	Auth
GET	/api/billing/invoices	List invoices with pagination, date range, and status filters	Yes
GET	/api/billing/invoices/:id	Get invoice detail including line items	Yes
GET	/api/billing/invoices/:id/pdf	Generate and download invoice PDF	Yes
GET	/api/billing/subscription	Get current subscription details and available plans	Yes
POST	/api/billing/subscription/change	Upgrade/downgrade plan with proration preview	Yes
POST	/api/billing/subscription/cancel	Cancel subscription at period end	Yes
GET	/api/billing/payment-methods	List saved payment methods	Yes
POST	/api/billing/payment-methods	Attach a new payment method (Stripe token)	Yes
DELETE	/api/billing/payment-methods/:id	Detach a payment method	Yes
POST	/api/billing/payment-methods/:id/default	Set payment method as default	Yes
GET	/api/billing/usage	Get usage data with metric and date range params	Yes
POST	/api/billing/webhook	Stripe webhook receiver (signature verified)	Stripe Sig

Security Considerations

• Webhook signature verification — Every incoming webhook is verified against the Stripe signing secret using stripe.webhooks.constructEvent(). Reject any request with an invalid or missing signature.
• Customer ID scoping — All billing queries are scoped to the authenticated user's Stripe customer ID. A user cannot access invoices, subscriptions, or payment methods belonging to another customer.
• PCI compliance — Never store raw card numbers. All payment method collection happens through Stripe Elements or Checkout, which tokenize card data client-side. Only Stripe tokens and payment method IDs are stored.
• Rate limiting on mutation endpoints — Subscription changes are limited to 10 requests per minute per customer to prevent rapid plan flipping and abuse. Payment method operations are limited to 30 per minute.
• Audit logging — All billing mutations (plan changes, payment attempts, refunds, payment method changes) are logged with timestamps, actor ID, and before/after state for compliance and support.
• CSRF protection — All POST/DELETE/PATCH endpoints validate a CSRF token. Webhook endpoint is exempt (uses Stripe signature instead).

Risks & Mitigations