Abrechnung

Plan & Nutzung für ein KI-Produkt, im Stil von Cursor, Claude und Vercel. Eine nach Modell aufgeteilte Nutzungsanzeige, die das Ende des Zyklus hochrechnet und warnt, bevor die Credits ausgehen, ein tägliches Diagramm zum Scrubben, ein Ausgabenlimit mit Warnungen, die du auf der Anzeige in der Vorschau siehst, Planwechsel mit exakter Anteilsberechnung, ein Kartenformular mit echter Validierung und Rechnungen als PDF-Download.

Open in new tab

Überblick

Billing ist der Bereich „Plan & Nutzung“ in den Einstellungen eines KI-Produkts. Er passt in einen SettingsShell-Bereich und deckt ab, wofür Leute auf diese Seite kommen: wie viel sie genutzt haben, ob es reicht, was sie zahlen und wie sie es ändern.

Die Nutzungsanzeige füllt sich nach Modell, mit einer helleren Verlängerung, die zeigt, wo der Zyklus im Tempo der letzten 7 Tage voraussichtlich endet. Reicht das über die enthaltenen Credits hinaus, sagt ein dezenter Hinweis wann: „In diesem Tempo sind deine Credits etwa am 24. Okt. aufgebraucht, 4 Tage vor dem Zurücksetzen“, mit Möglichkeiten, zusätzliche Nutzung zu aktivieren oder Pläne anzusehen. Darunter deckt ein tägliches Balkendiagramm auf Basis von Chart den ganzen Zyklus ab: vergangene Tage, heute in voller Stärke, der Rest des Zyklus als blasse prognostizierte Balken im jüngsten Tempo und eine gestrichelte Linie für das gleichmäßige Tempo, das den Zyklus tragen würde. Mit Hover oder Fokus und den Pfeiltasten liest du jeden Tag ab.

Limits sind ein Entwurf, wie jeder andere Settings-Bereich. Ziehst du die Warnschwelle oder aktivierst zusätzliche Nutzung, verschieben sich die Markierungen auf den Anzeigen sofort, die Anzeige für zusätzliche Nutzung gleitet herein und die Speicherleiste erscheint. Ein Limit unter dem in diesem Zyklus bereits Ausgegebenen wird mit dem Betrag abgelehnt.

Upgrades zeigen die exakte Anteilsberechnung, bevor etwas abgebucht wird: den neuen Plan für die verbleibenden Tage, die ungenutzten Tage des aktuellen und „Du zahlst heute 13,33 $“. Downgrades warten bis zum Ende der Laufzeit und listen auf, was wegfällt. Die Kündigung ist eine ehrliche Bestätigung ohne Angebote, der Plan bleibt bis zum Laufzeitende aktiv, und Keep Pro macht sie bis dahin rückgängig.

Das Kartenformular formatiert Zahlen beim Tippen, ohne den Cursor zu verschieben, prüft sie mit Luhn, erkennt die Marke und validiert Ablaufdatum und Sicherheitscode. Rechnungen haben Status-Badges, Pay now für fehlgeschlagene und werden als echte PDF-Dateien heruntergeladen.

Installation

Die Pro-Registry zu components.json hinzufügen

components.json

{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}

Token hinzufügen
Erstelle auf deiner Kontoseite einen Token und trage ihn in .env.local als HEXTAUI_PRO_TOKEN ein.

Den Block hinzufügen

pnpm dlx shadcn@latest add @hextaui-pro/billing

Verwendung

An deine API anbinden

BillingSettings zeigt die Daten, die du übergibst, und ruft dich bei jeder Änderung zurück. Gib in einem Callback etwas zurück oder wirf einen Fehler: Eine geworfene Meldung erscheint im Dialog, der sie ausgelöst hat, und nichts ändert sich, bis du neue Props übergibst.

"use client"

import * as React from "react"

import { SettingsSection, SettingsShell } from "../settings/settings"
import {
  BillingSettings,
  BillingSettingsSkeleton,
  type BillingSettingsProps,
} from "@/components/blocks/billing/billing-settings"

type BillingData = Pick<
  BillingSettingsProps,
  "plans" | "subscription" | "usage" | "spendLimit" | "paymentMethod" | "invoices" | "today"
>

async function post(url: string, body: unknown = {}) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  })
  if (!response.ok) {
    const { message } = await response.json().catch(() => ({ message: "" }))
    throw new Error(message || "Try again in a moment.")
  }
}

export function BillingPage() {
  const [data, setData] = React.useState<BillingData | null>(null)
  const [failed, setFailed] = React.useState(false)

  const load = React.useCallback(async () => {
    setFailed(false)
    try {
      const response = await fetch("/api/billing")
      if (!response.ok) throw new Error()
      setData(await response.json())
    } catch {
      setFailed(true)
    }
  }, [])

  React.useEffect(() => {
    void load()
  }, [load])

  const then = (url: string) => async (body?: unknown) => {
    await post(url, body)
    await load()
  }

  return (
    <SettingsShell sections={[{ id: "billing", label: "Plan & usage" }]}>
      <SettingsSection
        id="billing"
        status={failed ? "error" : data ? "ready" : "loading"}
        skeleton={<BillingSettingsSkeleton />}
        onRetry={load}
      >
        {data ? (
          <BillingSettings
            {...data}
            customer={{ name: "Mia Chen", email: "[email protected]" }}
            onChangePlan={then("/api/billing/plan")}
            onCancelPlan={then("/api/billing/cancel")}
            onResumePlan={then("/api/billing/resume")}
            onSpendLimitChange={then("/api/billing/limit")}
            onPayInvoice={(invoice) => then("/api/billing/pay")({ id: invoice.id })}
          />
        ) : null}
      </SettingsSection>
    </SettingsShell>
  )
}

Kartenaktualisierungen

onUpdatePaymentMethod erhält bereinigte Ziffern, das Ablaufdatum, den Sicherheitscode und die Marke, sobald das Formular seine Prüfungen besteht. Wirf einen Fehler, um im Dialog eine Ablehnung zu zeigen. Übergib die Daten in der Produktion an die Tokenisierung deines Zahlungsanbieters und speichere sie nie selbst.

"use client"

import * as React from "react"

import { BillingSettings, type BillingSettingsProps } from "@/components/blocks/billing/billing-settings"

export function BillingWithStripe(props: BillingSettingsProps) {
  return (
    <BillingSettings
      {...props}
      onUpdatePaymentMethod={async (card) => {
        const response = await fetch("/api/billing/card", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(card),
        })
        if (response.status === 402) {
          throw new Error("Your bank declined this card. Try another card.")
        }
        if (!response.ok) throw new Error("We couldn’t save that card. Try again.")
      }}
    />
  )
}

Deine eigenen Rechnungsdateien

Rechnungen werden als PDFs heruntergeladen, die im Browser aus den Rechnungsdaten erzeugt werden. Gib aus onDownloadInvoice einen Blob zurück, um stattdessen deine eigene Datei auszuliefern, oder gib einer Rechnung einen href.

"use client"

import * as React from "react"

import { BillingSettings, type BillingSettingsProps } from "@/components/blocks/billing/billing-settings"

export function BillingWithServerInvoices(props: BillingSettingsProps) {
  return (
    <BillingSettings
      {...props}
      seller="Acme Labs, Inc."
      onDownloadInvoice={async (invoice) => {
        const response = await fetch(`/api/invoices/${invoice.id}/pdf`)
        if (!response.ok) throw new Error("That invoice isn’t ready yet.")
        return response.blob()
      }}
    />
  )
}

Aufbau

Die Teile, die du zusammensetzt, von außen nach innen.

Part	Beschreibung
`BillingSettings`	Der Bereichsinhalt: Planübersicht, Nutzungsanzeigen und das tägliche Chart, Limits, Pläne, Zahlung, Rechnungen und Kündigung, mit ihren Dialogen.
`BillingSettingsSkeleton`	Ein Lade-Platzhalter in der Form des Bereichs. Übergib ihn an skeleton von SettingsSection.
`prorate`	Die Anteilsberechnung hinter dem Upgrade-Dialog, für deinen Server oder Tests.
`forecastUsage`	Die Prognose hinter der Anzeige und dem Hinweis auf das Aufbrauchen.
`createInvoicePdf`	Erzeugt das Rechnungs-PDF als Blob.

API-Referenz

BillingSettings

Preise sind in Cent, Datumswerte sind ISO-Tage wie 2026-10-28. Lass einen Callback weg, um seine Aktion auszublenden.

Prop	Typ	Standard
`plans`{ id, name, price, included, description?, features }. Features sind vollständige Listen pro Plan, sodass ein Downgrade auflisten kann, was fehlt. Ein Plan mit price 0 ist der Plan, zu dem Leute bei einer Kündigung wechseln.	`BillingPlan[]`	`–`
`subscription`{ planId, periodStart, periodEnd, status?, cancelAtPeriodEnd?, scheduledPlanId? }.	`BillingSubscription`	`–`
`usage`{ models: { id, name, used }[], daily: { date, used }[], extraRate, unit? }. extraRate sind Cent pro Einheit über das Enthaltene hinaus. unit ist standardmäßig "credits".	`BillingUsage`	`–`
`spendLimit`{ enabled, limit, alertAt }. limit ist in Cent und alertAt ein Prozentwert.	`BillingSpendLimit`	`–`
`paymentMethod`{ brand, last4, expMonth, expYear, name? }.	`BillingPaymentMethod \| null`	`–`
`invoices`{ id, number, date, description, amount, status, href?, lines?, paidWith? }. status ist paid, open, failed, refunded oder void.	`BillingInvoice[]`	`[]`
`today`Der Tag, den dein Server als heute ansieht. Wird für Anteilsberechnung, Prognosen und Kartenablauf verwendet, damit Server und Browser übereinstimmen.	`string`	`the last daily date`
`currency`Ein beliebiger ISO-Währungscode.	`string`	`"USD"`
`seller`Der Name oben auf erzeugten Rechnungen.	`string`	`"Hexta"`
`customer`Wird auf erzeugten Rechnungen unter Bill to gedruckt.	`{ name?, email? }`	`–`
`onChangePlan`Wird mit { planId, when, amountDue } aufgerufen. when ist "now" für Upgrades und "period_end" für Downgrades.	`(change) => void \| Promise`	`–`
`onCancelPlan`Zum Ende der Laufzeit kündigen.	`() => void \| Promise`	`–`
`onResumePlan`Macht eine Kündigung oder ein geplantes Downgrade rückgängig.	`() => void \| Promise`	`–`
`onSpendLimitChange`Speichert die Limits. Gib { limit: message } zurück, um einen Feldfehler zu zeigen.	`(limit) => void \| errors \| Promise`	`–`
`onUpdatePaymentMethod`Wird mit { number, expMonth, expYear, cvc, name, brand } aufgerufen, sobald das Formular gültig ist. Wirf einen Fehler, um eine Ablehnung zu zeigen.	`(card) => void \| Promise`	`–`
`onPayInvoice`Fügt Pay now zu offenen und fehlgeschlagenen Rechnungen hinzu.	`(invoice) => void \| Promise`	`–`
`onDownloadInvoice`Gib einen Blob zurück, um deine eigene Datei herunterzuladen, oder nichts, wenn du es selbst erledigt hast. Ohne ihn wird aus der Rechnung ein PDF erzeugt.	`(invoice) => Blob \| void \| Promise`	`–`

prorate

Gibt { kind, amountDue, charge, credit, daysLeft, totalDays, effectiveDate, nextBillingDate } zurück.

Prop	Typ	Standard
`options`Upgrades berechnen die Preisdifferenz für die verbleibenden Tage, einmal gerundet. Downgrades kosten nichts und beginnen bei periodEnd. Beim Wechsel von einem kostenlosen Plan wird ab heute ein voller Monat berechnet.	`{ from, to, periodStart, periodEnd, today }`	`–`

Tastatur

Taste	Aktion
`←→`	Bewegt bei fokussiertem Tagesdiagramm den Tooltip zum vorherigen oder nächsten Tag.
`Enter`	Prüft im Kartenformular die Angaben und speichert.
`⌘S`	Speichert geänderte Limits. Strg+S unter Windows und Linux.

Barrierefreiheit

Anzeigen nutzen role meter mit einem Werttext, der die Prognose und die Warnschwelle enthält, und die Aufschlüsselung nach Modell ist eine echte Liste.
Das Tagesdiagramm ist eine Figure namens „Tagesnutzung in diesem Zyklus“, beschrieben durch eine Zusammenfassung mit der Summe, dem aktuellen Tagesdurchschnitt, dem aktivsten Tag und dem gleichmäßigen Tempo. Eine visuell verborgene Tabelle listet jeden Tag, wobei prognostizierte Tage als Schätzungen markiert sind.
Planwechsel, Kündigungen, Kartenaktualisierungen und Downloads werden höflich angesagt. Fehler erscheinen als Alert im Dialog, der sie ausgelöst hat, und der Dialog bleibt mit deiner Eingabe offen.
Kartenfelder verwenden die Standard-Autocomplete-Tokens, sodass Browser und Passwortmanager sie ausfüllen können. Das erste ungültige Feld erhält den Fokus.
Inputs haben auf Touchscreens 16 px, damit iOS nicht zoomt, und Buttons wachsen auf 44 px.
Zahlen und Datumswerte werden auf Englisch mit festen Zeitzonen formatiert, sodass Server und Browser denselben Text rendern.

Gebaut mit

Die kostenlosen HextaUI-Komponenten, aus denen Billing besteht. Jede lässt sich einzeln installieren.

Code

4 Dateien, hinzugefügt zu components/blocks/billing.