Billing Components

BillingSection

Complete billing management

InvoiceHistory

List and download invoices

PaymentMethodManager

Add and manage payment methods

UsageOverview

Track usage and limits

Installation

All billing components are included in the SDK. Import what you need:

import {
  BillingSection,
  InvoiceHistory,
  PaymentMethodManager,
  UsageOverview,
} from '@sylphx/platform-sdk/react'

Provider Required

Billing components require the SylphxProvider wrapper for authentication context and API access.

BillingSection

A comprehensive billing management component that combines subscription details, plan selection, payment methods, and invoice history in one unified interface.

Full-featuredStripe Integration

Basic Usage

app/settings/billing/page.tsx

import { BillingSection } from '@sylphx/platform-sdk/react'

export default function BillingPage() {
  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Billing & Subscription</h1>
      <BillingSection />
    </div>
  )
}

Props

Property	Type	Description
`showPlans`	`boolean`= true	Display available plans for upgrade/downgrade
`showInvoices`	`boolean`= true	Display invoice history section
`showPaymentMethods`	`boolean`= true	Display payment method management
`showUsage`	`boolean`= true	Display usage metrics if applicable
`onPlanChange`	`(planId: string) => void`	Callback when user changes plan
`onCancelSubscription`	`() => void`	Callback when subscription is cancelled
`returnUrl`	`string`= window.location.href	URL to redirect after Stripe portal
`theme`	`ThemeVariables`	Custom theme override
`className`	`string`	Additional CSS classes

Advanced Examples

Subscription only

<BillingSection
  showPlans={false}
  showInvoices={false}
  showPaymentMethods={false}
  showUsage={false}
/>

Stripe Customer Portal

BillingSection includes a "Manage Billing" button that opens the Stripe Customer Portal, allowing users to update payment methods, download invoices, and manage their subscription directly.

InvoiceHistory

Displays a paginated list of invoices with status indicators, amounts, and download links. Integrates directly with Stripe for real-time data.

PaginatedDownloadable

Basic Usage

components/invoices.tsx

import { InvoiceHistory } from '@sylphx/platform-sdk/react'

export function InvoicesSection() {
  return (
    <div className="rounded-lg border p-6">
      <h2 className="text-lg font-semibold mb-4">Invoice History</h2>
      <InvoiceHistory />
    </div>
  )
}

Props

Property	Type	Description
`limit`	`number`= 10	Number of invoices per page
`showStatus`	`boolean`= true	Display payment status badges
`showDownload`	`boolean`= true	Show download PDF button
`showPagination`	`boolean`= true	Show pagination controls
`dateFormat`	`string`= "MMM d, yyyy"	Date format string (date-fns)
`onInvoiceClick`	`(invoice: Invoice) => void`	Callback when invoice row is clicked
`emptyState`	`ReactNode`	Custom empty state component
`className`	`string`	Additional CSS classes

Advanced Examples

Fewer invoices

<InvoiceHistory
  limit={5}
  showPagination={true}
/>

Invoice Status Badges

paid

pending

failed

draft

PaymentMethodManager

Allows users to add, remove, and set default payment methods. Supports credit/debit cards through Stripe Elements with full PCI compliance.

PCI CompliantStripe Elements

Basic Usage

components/payment-methods.tsx

import { PaymentMethodManager } from '@sylphx/platform-sdk/react'

export function PaymentMethodsSection() {
  return (
    <div className="rounded-lg border p-6">
      <h2 className="text-lg font-semibold mb-4">Payment Methods</h2>
      <PaymentMethodManager />
    </div>
  )
}

Props

Property	Type	Description
`allowAdd`	`boolean`= true	Allow adding new payment methods
`allowRemove`	`boolean`= true	Allow removing existing payment methods
`allowSetDefault`	`boolean`= true	Allow setting a default payment method
`showCardBrand`	`boolean`= true	Display card brand icon (Visa, Mastercard, etc.)
`onAdd`	`(paymentMethod: PaymentMethod) => void`	Callback when payment method is added
`onRemove`	`(paymentMethodId: string) => void`	Callback when payment method is removed
`onSetDefault`	`(paymentMethodId: string) => void`	Callback when default payment method changes
`addButtonText`	`string`= "Add Payment Method"	Custom text for add button
`className`	`string`	Additional CSS classes

Advanced Examples

View only mode

<PaymentMethodManager
  allowAdd={false}
  allowRemove={false}
  allowSetDefault={false}
/>

Stripe Setup Required

PaymentMethodManager requires Stripe to be properly configured in your Sylphx dashboard. Ensure you've connected your Stripe account and set up the necessary webhook endpoints.

Card Display

Each payment method displays the card brand, last 4 digits, and expiration date:

VISA

**** **** **** 4242

Expires 12/25

Default

UsageOverview

Displays current usage metrics for metered billing plans. Shows progress bars, usage limits, and billing cycle information.

Metered BillingReal-time

Basic Usage

components/usage.tsx

import { UsageOverview } from '@sylphx/platform-sdk/react'

export function UsageSection() {
  return (
    <div className="rounded-lg border p-6">
      <h2 className="text-lg font-semibold mb-4">Current Usage</h2>
      <UsageOverview />
    </div>
  )
}

Props

Property	Type	Description
`metrics`	`string[]`	Specific metrics to display (shows all if not specified)
`showProgressBar`	`boolean`= true	Display visual progress bars
`showPercentage`	`boolean`= true	Show usage percentage
`showBillingCycle`	`boolean`= true	Display current billing cycle dates
`warningThreshold`	`number`= 80	Percentage at which to show warning (0-100)
`dangerThreshold`	`number`= 95	Percentage at which to show danger state (0-100)
`onLimitReached`	`(metric: string) => void`	Callback when usage hits 100%
`onWarningThreshold`	`(metric: string, percentage: number) => void`	Callback when warning threshold is reached
`refreshInterval`	`number`= 60000	Auto-refresh interval in milliseconds
`className`	`string`	Additional CSS classes

Advanced Examples

Filter displayed metrics

<UsageOverview
  metrics={['api_calls', 'storage', 'bandwidth']}
  showBillingCycle={true}
/>

Usage Metrics Display

The component displays each metric with a progress bar that changes color based on usage:

API Calls4500 / 10000 (45%)

Storage8.2GB / 10GB (82%)

Team Members9 / 10 (90%)

Metered Billing

UsageOverview is designed for metered billing plans. If your plan doesn't include usage-based pricing, this component will show "No usage metrics available".

Building a Billing Page

Here's how to combine these components to build a complete billing settings page:

app/settings/billing/page.tsx

import {
  BillingSection,
  InvoiceHistory,
  PaymentMethodManager,
  UsageOverview,
} from '@sylphx/platform-sdk/react'

export default function BillingSettingsPage() {
  return (
    <div className="max-w-4xl mx-auto py-8 space-y-8">
      <div>
        <h1 className="text-2xl font-bold">Billing & Subscription</h1>
        <p className="text-muted-foreground mt-1">
          Manage your subscription, payment methods, and view invoices
        </p>
      </div>

      {/* Current Plan & Usage */}
      <section className="rounded-xl border p-6">
        <h2 className="text-lg font-semibold mb-4">Current Plan</h2>
        <BillingSection
          showInvoices={false}
          showPaymentMethods={false}
        />
      </section>

      {/* Usage Metrics */}
      <section className="rounded-xl border p-6">
        <h2 className="text-lg font-semibold mb-4">Usage This Month</h2>
        <UsageOverview
          warningThreshold={80}
          dangerThreshold={95}
        />
      </section>

      {/* Payment Methods */}
      <section className="rounded-xl border p-6">
        <h2 className="text-lg font-semibold mb-4">Payment Methods</h2>
        <PaymentMethodManager />
      </section>

      {/* Invoice History */}
      <section className="rounded-xl border p-6">
        <h2 className="text-lg font-semibold mb-4">Invoices</h2>
        <InvoiceHistory limit={5} />
      </section>
    </div>
  )
}

Theming

All billing components support custom theming through the theme prop:

import { BillingSection, type ThemeVariables } from '@sylphx/platform-sdk/react'

const customTheme: ThemeVariables = {
  colorPrimary: '#6366f1',
  colorBackground: '#fafafa',
  colorText: '#1f2937',
  colorMutedForeground: '#6b7280',
  colorBorder: '#e5e7eb',
  colorDestructive: '#ef4444',
  colorSuccess: '#22c55e',
  colorWarning: '#f59e0b',
  fontFamily: 'Inter, sans-serif',
  borderRadius: '0.75rem',
}

<BillingSection theme={customTheme} />
<InvoiceHistory theme={customTheme} />
<PaymentMethodManager theme={customTheme} />
<UsageOverview theme={customTheme} />

Related Hooks

For more control, use the underlying hooks:

import {
  useBilling,
  useSubscription,
  useInvoices,
  usePaymentMethods,
  useUsage,
} from '@sylphx/platform-sdk/react'

function CustomBillingUI() {
  const { subscription, plans, isLoading } = useBilling()
  const { invoices, hasMore, loadMore } = useInvoices()
  const { paymentMethods, addPaymentMethod, removePaymentMethod } = usePaymentMethods()
  const { usage, metrics, refresh } = useUsage()

  // Build your own custom UI with these hooks
  return (
    <div>
      {/* Custom implementation */}
    </div>
  )
}

BillingSection

InvoiceHistory

PaymentMethodManager

UsageOverview

Installation

Provider Required

BillingSection

Basic Usage

Props

Advanced Examples

Stripe Customer Portal

InvoiceHistory

Basic Usage

Props

Advanced Examples

Invoice Status Badges

PaymentMethodManager

Basic Usage

Props

Advanced Examples

Stripe Setup Required

Card Display

UsageOverview

Basic Usage

Props

Advanced Examples

Usage Metrics Display

Metered Billing

Building a Billing Page

Theming

Related Hooks

Plans & Pricing

Checkout

Webhooks