🏪 Customer Portal Module
Self-service customer portal for managing billing, subscriptions, and payment methods with Stripe.
Self-Service Portal
Complete customer self-service with Stripe's portal
Billing Management
View invoices, payment history, and receipts
Subscription Control
Cancel, pause, or modify subscriptions
Payment Methods
Add, remove, and update payment methods
React Hooks
useCustomerPortal hook for easy integration
Secure Access
Stripe-hosted secure portal sessions
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)
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.
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)
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.
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>
);
}
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.
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