🏪 Customer Portal Module

Self-service customer portal for managing billing, subscriptions, and payment methods with Stripe.

✨ Features
Self-Service

Self-Service Portal

Complete customer self-service with Stripe's portal

Billing

Billing Management

View invoices, payment history, and receipts

Subscriptions

Subscription Control

Cancel, pause, or modify subscriptions

Payment

Payment Methods

Add, remove, and update payment methods

Hooks

React Hooks

useCustomerPortal hook for easy integration

Secure

Secure Access

Stripe-hosted secure portal sessions

🚀 Installation
npx shadcn@latest add "https://supremetoolkit.in/r/customer-portal"

This installs:

  • • Stripe customer portal configuration
  • • useCustomerPortal hook for portal access
  • • API route for creating portal sessions
  • • Server actions for portal management
  • • Secure session handling and validation
  • • Required dependencies (stripe, @stripe/stripe-js)
🔧 Environment Variables & Setup

Requires Existing Stripe Customers

The customer portal is for existing Stripe customers with subscriptions or payment history. Install the subscriptions module first to create customers.

1. Add Stripe API Keys:

# .env.local
# Required - Get these from your Stripe Dashboard
STRIPE_SECRET_KEY=sk_test_your_secret_key_here
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

2. Configure Customer Portal in Stripe Dashboard:

• Go to Stripe Dashboard → Settings → Billing → Customer Portal

• Enable the customer portal

• Configure allowed features:

  • - Update payment methods
  • - View billing history
  • - Download invoices
  • - Cancel subscriptions (optional)
  • - Update subscription quantities (optional)

• Set your business information and branding

3. Set Return URL:

Configure where customers return after using the portal:

// In your customer portal configuration
return_url: 'https://yourdomain.com/dashboard'

4. Prerequisites:

• Install authentication module for user management

• Install subscriptions module to create Stripe customers

• Ensure users have associated Stripe customer IDs

• Test with customers who have active subscriptions

Customer ID Required

Each user must have a Stripe customer ID stored in your database. This is typically created when they make their first purchase or subscription.

📦 What's Included

useCustomerPortal

Create and redirect to Stripe customer portal

const { redirectToPortal, loading, error } = useCustomerPortal()

createPortalSession

Create portal session without redirect

const url = await createPortalSession(customerId, returnUrl)
⚙️ Configuration

Environment Variables:

# .env.local
STRIPE_SECRET_KEY=sk_test_your_secret_key_here
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

# Optional: Configure in config.tsx
NEXT_PUBLIC_APP_URL=https://yourapp.com

Stripe Dashboard Setup:

1. Go to Stripe Dashboard → Settings → Customer Portal

2. Configure portal features (subscriptions, payment methods, etc.)

3. Set up business information and branding

4. Configure allowed actions (cancel, pause, resume subscriptions)

5. Set up email notifications and receipts

Portal Configuration

The customer portal is fully managed by Stripe. You can customize its appearance, features, and behavior through your Stripe Dashboard settings.

🔧 Usage Examples

Simple portal access button:

import { useCustomerPortal } from '@/hooks/use-stripe';

export default function ManageBillingButton({ customerId }) {
  const { redirectToPortal, loading, error } = useCustomerPortal();

  const handleManageBilling = async () => {
    try {
      await redirectToPortal(customerId, '/account');
    } catch (err) {
      console.error('Failed to open customer portal:', err);
      alert('Failed to open billing portal. Please try again.');
    }
  };

  return (
    <div>
      <button
        onClick={handleManageBilling}
        disabled={loading}
        className="bg-blue-600 text-white px-4 py-2 rounded disabled:opacity-50"
      >
        {loading ? 'Opening...' : 'Manage Billing'}
      </button>

      {error && (
        <p className="text-red-500 text-sm mt-2">
          Error: {error}
        </p>
      )}
    </div>
  );
}

Portal session without redirect:

import { useCustomerPortal } from '@/hooks/use-stripe';

export default function CustomPortalHandler({ customerId }) {
  const { createPortalSession, loading } = useCustomerPortal();

  const handleGetPortalUrl = async () => {
    try {
      const portalUrl = await createPortalSession(customerId, '/dashboard');

      // You can now use the URL as needed
      console.log('Portal URL:', portalUrl);

      // Open in new tab
      window.open(portalUrl, '_blank');

      // Or save for later use
      localStorage.setItem('portalUrl', portalUrl);

    } catch (err) {
      console.error('Failed to create portal session:', err);
    }
  };

  return (
    <button
      onClick={handleGetPortalUrl}
      disabled={loading}
      className="border border-gray-300 px-4 py-2 rounded"
    >
      {loading ? 'Creating...' : 'Get Portal URL'}
    </button>
  );
}
🌟 Best Practices

Portal Configuration

Configure the customer portal in your Stripe Dashboard to match your brand and enable only the features your customers need.

Return URLs

Always provide meaningful return URLs that bring users back to relevant pages in your application.

Error Handling

Implement proper error handling for portal access failures and provide clear feedback to users.

Analytics Tracking

Track portal usage to understand customer behavior and identify potential issues or opportunities.

Security

Never expose customer IDs in URLs or client-side code. Always validate customer access server-side.

User Experience

Provide clear context about what users can do in the portal and what to expect when they access it.

🎯 What Customers Can Do

Subscription Management:

  • • Cancel subscriptions
  • • Pause and resume subscriptions
  • • Change subscription plans
  • • Update billing frequency
  • • View subscription history

Payment Management:

  • • Add new payment methods
  • • Update existing cards
  • • Set default payment method
  • • Remove old payment methods
  • • Update billing address

Billing History:

  • • View all invoices
  • • Download receipts
  • • See payment history
  • • Track upcoming charges
  • • View failed payments

Account Information:

  • • Update contact information
  • • Manage tax information
  • • Set billing preferences
  • • Configure email notifications
  • • View account details