stripe-subscription-ux（Stripe subscription UX 浏览器）

Subscription Management UX

Every Stripe integration must include a world-class subscription management experience. Users should never wonder about their billing status.

Non-Negotiable Requirements

A complete Stripe integration MUST include UI for users to:

1. View Current Plan

• Plan name (e.g., "Pro", "Monthly", "Annual")
• Subscription status (active, trialing, canceled, past_due)
• Clear visual indicator of status
• Trial remaining (if applicable)

2. See Billing Cycle

• Next billing date
• Amount to be charged
• Billing frequency (monthly/annual)
• Current period start/end dates

3. View Payment Method

• Card brand and last 4 digits (e.g., "Visa ending in 4242")
• Expiration date
• Update payment method button

4. Manage Subscription

• Cancel subscription
• Resume canceled subscription (if before period end)
• Upgrade/downgrade (if multiple tiers)
• Switch billing frequency (monthly ↔ annual)

5. View Billing History

• Past invoices with dates and amounts
• Download invoice PDFs
• Payment status (paid, failed, refunded)

Implementation Approaches

Option A: Stripe Customer Portal (Recommended)

Use Stripe's built-in Customer Portal for most functionality:

// Create portal session
const portalSession = await stripe.billingPortal.sessions.create({
  customer: stripeCustomerId,
  return_url: `${APP_URL}/settings`,
});

// Redirect user to portal
redirect(portalSession.url);

Pros:

• Minimal code
• Stripe handles PCI compliance
• Always up-to-date with Stripe features
• Mobile-responsive

Cons:

• Less control over styling
• Branding limited to Stripe's options
• User leaves your site briefly

Option B: Custom UI + Stripe API

Build custom UI that calls Stripe API:

// Fetch subscription details
const subscription = await stripe.subscriptions.retrieve(subscriptionId, {
  expand: ['default_payment_method', 'latest_invoice'],
});

// Display in your UI
const planName = subscription.items.data[0].price.nickname;
const status = subscription.status;
const currentPeriodEnd = new Date(subscription.current_period_end * 1000);
const paymentMethod = subscription.default_payment_method as Stripe.PaymentMethod;
const cardBrand = paymentMethod?.card?.brand;
const cardLast4 = paymentMethod?.card?.last4;

Pros:

• Full control over UX
• Stays within your app
• Custom branding

Cons:

• More code to maintain
• Must handle payment method updates carefully (PCI)
• Must implement all edge cases

Option C: Hybrid (Best of Both)

Custom settings page for display, Stripe Portal for mutations:

// Custom display UI
<SettingsCard>
  <h2>Subscription</h2>
  <p>Plan: {planName}</p>
  <p>Status: <StatusBadge status={status} /></p>
  <p>Next billing: {formatDate(currentPeriodEnd)}</p>
  <p>Card: {cardBrand} ending in {cardLast4}</p>

  {/* Mutations go to Stripe Portal */}
  <Button onClick={openStripePortal}>
    Manage Subscription
  </Button>
</SettingsCard>

This is the recommended approach.

Component Structure

Typical implementation needs:

components/
├── billing/
│   ├── SubscriptionCard.tsx      # Current plan overview
│   ├── BillingCycleInfo.tsx      # Next billing date, amount
│   ├── PaymentMethodDisplay.tsx  # Card on file
│   ├── BillingHistory.tsx        # Past invoices
│   ├── ManageSubscriptionButton.tsx  # Opens portal
│   └── TrialBanner.tsx           # Trial status/countdown

Settings page:

// app/(dashboard)/settings/page.tsx
export default function SettingsPage() {
  return (
    <div>
      <h1>Settings</h1>

      <section>
        <h2>Subscription</h2>
        <SubscriptionCard />
        <BillingCycleInfo />
        <PaymentMethodDisplay />
        <ManageSubscriptionButton />
      </section>

      <section>
        <h2>Billing History</h2>
        <BillingHistory />
      </section>
    </div>
  );
}

API Requirements

Backend needs to expose:

// convex/billing.ts (or API route)

// Get subscription details for display
export const getSubscriptionDetails = query({
  handler: async (ctx) => {
    const userId = await requireAuth(ctx);
    const user = await ctx.db.get(userId);

    return {
      status: user.subscriptionStatus,
      planName: user.planName ?? 'Pro',
      currentPeriodEnd: user.currentPeriodEnd,
      cancelAtPeriodEnd: user.cancelAtPeriodEnd,
      trialEndsAt: user.trialEndsAt,
      // Payment method from Stripe (cached or fetched)
      paymentMethod: user.paymentMethodSummary,
    };
  },
});

// Create Stripe Portal session
export const createPortalSession = action({
  handler: async (ctx) => {
    const userId = await requireAuth(ctx);
    const user = await ctx.runQuery(internal.users.get, { userId });

    if (!user.stripeCustomerId) {
      throw new ConvexError("No billing account");
    }

    const session = await stripe.billingPortal.sessions.create({
      customer: user.stripeCustomerId,
      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/settings`,
    });

    return { url: session.url };
  },
});

// Get billing history (invoices)
export const getBillingHistory = action({
  handler: async (ctx) => {
    const userId = await requireAuth(ctx);
    const user = await ctx.runQuery(internal.users.get, { userId });

    if (!user.stripeCustomerId) {
      return { invoices: [] };
    }

    const invoices = await stripe.invoices.list({
      customer: user.stripeCustomerId,
      limit: 10,
    });

    return {
      invoices: invoices.data.map(inv => ({
        id: inv.id,
        date: inv.created,
        amount: inv.amount_paid,
        status: inv.status,
        invoicePdf: inv.invoice_pdf,
      })),
    };
  },
});

Schema Requirements

User model needs:

// convex/schema.ts
users: defineTable({
  // ... existing fields

  // Subscription state
  subscriptionStatus: v.optional(v.string()),
  stripeCustomerId: v.optional(v.string()),
  stripeSubscriptionId: v.optional(v.string()),

  // Billing cycle
  currentPeriodEnd: v.optional(v.number()),
  cancelAtPeriodEnd: v.optional(v.boolean()),

  // Trial
  trialEndsAt: v.optional(v.number()),

  // Payment method cache (update from webhooks)
  paymentMethodSummary: v.optional(v.object({
    brand: v.string(),
    last4: v.string(),
    expMonth: v.number(),
    expYear: v.number(),
  })),

  // Plan info
  planName: v.optional(v.string()),
  planInterval: v.optional(v.string()), // 'month' or 'year'
})

Webhook Updates

To keep payment method cached, handle:

case 'customer.subscription.updated':
case 'payment_method.attached':
case 'payment_method.updated':
  // Extract payment method details
  const pm = event.data.object.default_payment_method;
  if (pm?.card) {
    await ctx.runMutation(internal.users.updatePaymentMethod, {
      userId,
      paymentMethod: {
        brand: pm.card.brand,
        last4: pm.card.last4,
        expMonth: pm.card.exp_month,
        expYear: pm.card.exp_year,
      },
    });
  }

UX Best Practices

Status Messaging

Trial Banner (Credit Card Upfront Model)

With credit card collected upfront, the trial banner focuses on when billing starts:

{user.subscriptionStatus === 'trialing' && (
  <Banner variant="info">
    Your free trial ends on {formatDate(trialEndsAt)}.
    You'll be charged ${amount} unless you cancel.
    <Link href="/settings">Manage subscription</Link>
  </Banner>
)}

Key messaging for credit card upfront:

• "Free trial ends on [date]" (not "X days left")
• "You won't be charged until [date]"
• "Cancel anytime before [date] to avoid charges"
• Link to manage/cancel, not to "subscribe"

### Canceled State

When subscription is canceled but still in period:

<Card className="border-yellow-500"> <p>Your subscription has been canceled.</p> <p>You have access until {formatDate(currentPeriodEnd)}.</p> <Button onClick={resubscribe}>Resume Subscription</Button> </Card>

### Payment Failed State

Urgent but not alarmist:

<Card className="border-red-500"> <p>Your last payment failed.</p> <p>Please update your payment method to avoid losing access.</p> <Button onClick={openStripePortal}>Update Payment</Button> </Card>

## Verification Checklist

A complete subscription management UX should pass:

- User can see current plan name
- User can see subscription status with clear indicator
- User can see next billing date and amount
- User can see payment method on file
- User can access billing history
- User can cancel subscription
- User can resume canceled subscription (if in period)
- User can update payment method
- Trial users see trial status and remaining time
- Failed payment shows clear call-to-action
- All states have appropriate messaging

## Integration with Stripe Workflow

This skill is invoked by:

- `stripe-scaffold` — generates UX components
- `stripe-audit` — checks for UX completeness
- `stripe-verify` — tests UX functionality

## Related Skills

- `subscription-patterns` — State management and access control
- `billing-security` — Security considerations
- `stripe-configure` — Portal configuration in Stripe Dashboard