Customer portal: a Payments & Stripe guide for developers

A self-service customer portal transforms your support burden. Instead of handling billing inquiries manually, your customers can update payment methods, download invoices, and manage their subscription tier without contacting your team. In this guide, we'll walk through building a customer portal: a Payments & Stripe guide for developers that handles the most common billing tasks and reduces support tickets significantly.

Why a customer portal matters

Before we dive into implementation, let's establish why this matters. Support teams in mid-market SaaS companies typically spend 20–30% of their bandwidth on repetitive billing questions. "Can I update my card?" "How do I cancel?" "Can you send last month's invoice?" These are easily automatable, yet they clog your support queue and frustrate customers with response delays.

A well-designed portal doesn't just reduce tickets—it improves retention. Customers who can instantly change plans or fix a declined card are less likely to churn out of frustration. And from a compliance perspective, giving users direct access to their invoices and payment history meets audit requirements and reduces your liability.

Update cards and download invoices

The most frequent support request involves payment method updates. A customer's card expires, gets declined, or they simply want to switch to a corporate card. Without a portal, they email support, wait for a response, and potentially miss a billing cycle in the meantime.

Stripe's Customer object stores payment methods as PaymentMethod resources. To let customers update their card, we expose a simple endpoint that creates a SetupIntent—Stripe's way of securely collecting a new payment method without charging immediately.

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2024-04-10',
});

// Create a SetupIntent for card update
async function createCardUpdateIntent(customerId: string) {
  const setupIntent = await stripe.setupIntents.create({
    customer: customerId,
    usage: 'off_session', // Future charges don't need confirmation
    payment_method_types: ['card'],
  });

  return {
    client_secret: setupIntent.client_secret,
    setupIntentId: setupIntent.id,
  };
}

On the frontend, you embed Stripe's card element and confirm the setup intent using the client secret. Once confirmed, the new card becomes the customer's default payment method automatically.

Invoices are equally straightforward. Stripe generates invoices as downloadable PDFs. Your backend simply retrieves the customer's invoice list and passes the pdf URL to the frontend, or you can stream the PDF directly:

// Retrieve invoices for a customer
async function getCustomerInvoices(customerId: string) {
  const invoices = await stripe.invoices.list({
    customer: customerId,
    limit: 12,
  });

  return invoices.data.map((invoice) => ({
    id: invoice.id,
    number: invoice.number,
    amount: invoice.total,
    currency: invoice.currency,
    date: new Date(invoice.created * 1000),
    pdfUrl: invoice.pdf, // Direct download link
    status: invoice.status,
  }));
}

In production, you'll want to verify that the logged-in user owns the customer record before returning sensitive data. Use your internal user-to-Stripe-customer mapping, typically stored in your database.

Change or cancel plans

Subscription management is where a portal saves the most support overhead. Customers want to upgrade, downgrade, or pause their subscription without friction. Stripe subscriptions have a clean update flow: you modify the subscription at a specific date—immediately, at the next billing cycle, or after a trial ends.

In a typical SaaS product, you'd offer plan tiers: Starter, Pro, Enterprise. A customer on Starter can upgrade to Pro immediately (prorating charges), or downgrade at their next renewal to avoid refund complexity.

// Update subscription to a new plan
async function changePlan(
  subscriptionId: string,
  newPriceId: string,
  prorationBehavior: 'create_prorations' | 'none' | 'always_invoice' = 'create_prorations'
) {
  const subscription = await stripe.subscriptions.retrieve(subscriptionId);

  // Assuming single-item subscriptions (common pattern)
  const updated = await stripe.subscriptions.update(subscriptionId, {
    items: [
      {
        id: subscription.items.data[0].id,
        price: newPriceId,
      },
    ],
    proration_behavior: prorationBehavior,
    billing_cycle_anchor: 'unchanged', // Keep existing billing date
  });

  return updated;
}

// Cancel subscription at end of current period (retain access until renewal)
async function cancelAtPeriodEnd(subscriptionId: string) {
  const updated = await stripe.subscriptions.update(subscriptionId, {
    cancel_at_period_end: true,
  });

  return {
    status: updated.status,
    cancelAt: new Date(updated.cancel_at_period_end ? updated.current_period_end * 1000 : 0),
  };
}

// Immediate cancellation
async function cancelImmediately(subscriptionId: string) {
  await stripe.subscriptions.del(subscriptionId);
  return { status: 'canceled' };
}

Notice we're using cancel_at_period_end rather than immediate cancellation. This is a best practice—customers retain access through their paid period, reducing churn psychology and legal complications. You can offer both options in your UI, but default to the gentler approach.

One real-world scenario: a startup on your Pro plan realizes they overspent and want to downgrade to Starter mid-month. With prorationBehavior: 'create_prorations', Stripe automatically calculates the credit and applies it to their next invoice. Your support team doesn't have to debate refund policy.

Configure allowed actions

Not all customers should have the same portal permissions. An enterprise customer might not be allowed to cancel—you want sales to retain the relationship. A free-trial user might only view invoices. You configure these controls via a permissions model in your application logic.

Store allowed actions in your database or derive them from subscription metadata:

interface PortalPermissions {
  canUpdatePaymentMethod: boolean;
  canChangeSubscription: boolean;
  canCancelSubscription: boolean;
  canDownloadInvoices: boolean;
  allowedPlanIds?: string[]; // Restrict upgrade/downgrade destinations
}

async function getPortalPermissions(
  customerId: string,
  subscription: Stripe.Subscription
): Promise {
  // Fetch customer from your database to check account tier, contract terms, etc.
  const customer = await db.customers.findOne({ stripeCustomerId: customerId });

  const isEnterprise = customer?.tier === 'enterprise';
  const isTrialing = subscription.status === 'trialing';

  return {
    canUpdatePaymentMethod: true, // Always allow
    canChangeSubscription: !isEnterprise, // Enterprise: locked plan
    canCancelSubscription: !isEnterprise && !isTrialing, // No cancel during trial
    canDownloadInvoices: true,
    allowedPlanIds: isEnterprise ? undefined : ['price_starter', 'price_pro'], // Restrict options
  };
}

Your API endpoint exposes this permissions object alongside the customer data. The frontend then conditionally renders buttons and form fields. This approach scales well: if you later add restrictions (e.g., "no cancellation if balance is negative"), you update one function.

You can also use Stripe's metadata field to tag subscriptions with internal business rules, though we recommend keeping critical logic in your application layer for clarity and auditability.

Fewer support tickets

The cumulative impact of a self-service portal is measurable. In typical deployments we've seen:

• Card update: 40% reduction in "payment declined" support emails. Customers fix expired cards themselves instead of waiting for your team.
• Subscription changes: 50% reduction in plan-change and cancellation requests. What took a support email and 4-hour response time now takes 30 seconds.
• Invoice requests: 25% reduction in accounting-related tickets. "Can you email me an invoice?" is now self-service.

Beyond volume, support quality improves. Your team spends cycles on genuinely complex issues—refunds, disputes, feature questions—instead of repetitive billing mechanics. And customers are happier: they're no longer blocked by business hours or response-time SLAs.

One secondary benefit: audit trail. Stripe records every subscription change and payment method update with timestamps. Your database logs which user changed what and when. This transparency helps in disputes and provides compliance documentation without extra effort.

Common mistakes

• Skipping permission checks: A developer hardcodes all actions as available, and an enterprise customer accidentally cancels their subscription. Always fetch and validate permissions server-side before processing changes.
• Immediate cancellation by default: Offering only "Cancel now" instead of "Cancel at period end" leads to churn and refund requests. Default to the gentler option; advanced users can choose immediate if needed.
• Not handling proration edge cases: If a customer downgrades from Pro to Starter mid-cycle, Stripe's prorating assumes standard rates. If you have custom pricing, manually reconcile or use proration_behavior: 'none' and invoice manually.
• Exposing raw Stripe responses: Return cleaned, user-friendly data structures to the frontend. Don't serialize the entire Stripe object—it's verbose, potentially contains sensitive metadata, and changes with API updates.
• Missing idempotency keys: If a network error occurs mid-update, retrying without an idempotency key might create duplicate changes. Always include them in production:

const updated = await stripe.subscriptions.update(
  subscriptionId,
  { items: [...] },
  { idempotencyKey: `update-${subscriptionId}-${timestamp}` }
);

Key takeaways

• A customer portal dramatically reduces support overhead by enabling self-service card updates, plan changes, and invoice downloads.
• Use Stripe SetupIntent for card updates and subscriptions.update() with prorating for plan changes—both are battle-tested patterns.
• Implement a permissions layer so enterprise and trial customers have restricted actions; store logic in your application, not Stripe metadata.
• Default to cancel_at_period_end: true instead of immediate cancellation to reduce churn and support overhead.
• Always validate permissions server-side, include idempotency keys, and sync billing state back to your database on successful changes.
• A well-built portal typically cuts billing-related support tickets by 30–50% within the first month of launch.