Implementation:Helicone Helicone Credits Page

Knowledge Sources	Helicone
Domains	Billing, Frontend
Last Updated	2026-02-14 06:32 GMT

Overview

Credits and billing management page component that provides a comprehensive view of credit balance, transaction history, per-model usage breakdown, invoices, and discount management.

Description

credits.tsx implements the Credits page as a Next.js page component with AuthLayout, providing four tabbed views for billing and usage management:

Overview Tab:

• Current Balance Card -- Displays the user's credit balance with adaptive decimal precision formatting.
• Buy Credits Card -- Opens a PaymentModal for purchasing credits.
• Auto Top-Up Card -- Shows auto top-up status (active/inactive), trigger threshold, top-up amount, and last top-up date. Opens an AutoTopoffModal for configuration. Auto-opens when returning from Stripe setup (?setup=success).
• Recent Transactions -- Paginated transaction list with configurable page size (5/10/25/50). Each transaction shows date, status icon (CheckCircle, Clock, AlertCircle, XCircle), amount, and refund details. Supports token-based cursor pagination.

Usage Tab:

• Date range picker (From/To) defaulting to the last 30 days.
• Total cost summary for the selected period.
• Sortable table with columns: Model, Provider, Input tokens, Output tokens, Cache Read tokens, Cache Write tokens, per-1M pricing for each, and total Cost.
• Sort by any column (ascending/descending) using SortableHeader components.

Invoices Tab (conditional):

• Shown only when invoices exist.
• Table with Period, Created date, Subtotal, Total, Saved amount, and Status (with link to hosted Stripe invoice).

Discounts Tab (conditional):

• Shown only when discounts exist.
• Table showing Provider, Model Pattern, and discount percentage.

Data Hooks:

• useCredits() -- Fetches credit balance
• useCreditTransactions() -- Fetches paginated transaction history
• useAutoTopoffSettings() -- Fetches auto top-off configuration
• useSpendBreakdown() -- Fetches per-model spend data for a date range
• useInvoices() -- Fetches invoice history
• useDiscounts() -- Fetches discount rules

Helper Functions:

• formatTokens -- Formats token counts (e.g., 1.5M, 200K)
• formatPrice -- Formats per-unit prices with appropriate precision
• formatCost -- Formats cost values with adaptive decimal places

Usage

This page is accessible at /credits in the Helicone dashboard. It requires authentication (wrapped in AuthLayout). The tab state is synchronized with the URL query parameter ?tab= for deep linking.

Code Reference

Source Location

• Repository: Helicone
• File: web/pages/credits.tsx

Signature

const Credits: NextPageWithLayout<void> = () => {
  // ... component implementation
};

Credits.getLayout = function getLayout(page: ReactElement) {
  return <AuthLayout>{page}</AuthLayout>;
};

export default Credits;

Import

// This is a Next.js page, accessed via routing at /credits
// No direct import needed; it is consumed by the Next.js router

I/O Contract

Data Dependencies

Hook	Returns	Description
useCredits()	{ balance: number }	Current credit balance
useCreditTransactions({ limit, page })	{ purchases: PurchasedCredits[], hasMore, nextPage }	Paginated transaction history
useAutoTopoffSettings()	{ enabled, thresholdCents, topoffAmountCents, lastTopoffAt }	Auto top-up configuration
useSpendBreakdown({ startDate, endDate })	{ models: ModelSpend[], totalCost }	Per-model usage and cost breakdown
useInvoices()	Invoice[]	Invoice history with Stripe links
useDiscounts()	Discount[]	Active discount rules

URL Parameters

Parameter	Type	Description
tab	string	Active tab ("overview", "usage", "invoices", "discounts")
setup	string	When "success", auto-opens the Auto Top-Up modal

Component Structure

Credits
  Header (title="Credits", refresh button)
  Tabs
    TabsContent: Overview
      Card: Current Balance
      Grid:
        Card: Buy Credits -> PaymentModal
        Card: Auto Top-Up -> AutoTopoffModal
      Card: Recent Transactions (paginated)
    TabsContent: Usage
      DatePicker range + Total cost
      Sortable Table (Model, Provider, Tokens, Pricing, Cost)
    TabsContent: Invoices (conditional)
      Table (Period, Created, Subtotal, Total, Saved, Status)
    TabsContent: Discounts (conditional)
      Table (Provider, Model Pattern, Discount)
  PaymentModal
  AutoTopoffModal
  LastTopoffDetailsModal

Usage Examples

// Navigate to the credits page with the usage tab active
router.push("/credits?tab=usage");

// The page automatically loads data via hooks
// and renders the appropriate tab based on the URL

Related Pages

• Principle:Helicone_Helicone_Legal_Compliance