Facturation

Forfait et utilisation pour un produit d’IA, dans le style de Cursor, Claude et Vercel. Un compteur d’utilisation réparti par modèle qui projette la fin du cycle et prévient avant la fin des crédits, un graphique quotidien explorable, une limite de dépenses avec des alertes prévisualisables sur le compteur, des changements de forfait avec proratisation exacte, un formulaire de carte avec une vraie validation, et des factures téléchargeables en PDF.

Open in new tab

Vue d’ensemble

Billing est la section Forfait et utilisation des paramètres d’un produit d’IA. Elle s’intègre dans une section de SettingsShell et couvre ce pour quoi les gens viennent sur cette page : combien ils ont consommé, si cela suffira, ce qu’ils paient et comment le modifier.

Le compteur d’utilisation se remplit par modèle, avec un prolongement plus clair qui montre où le cycle finira probablement au rythme des 7 derniers jours. Quand cela dépasse les crédits inclus, une note discrète indique quand : « At this pace you’ll run out around Oct 24, 4 days before your credits reset », avec des moyens d’activer l’utilisation supplémentaire ou de voir les forfaits. En dessous, un graphique à barres quotidien construit sur Chart couvre tout le cycle : jours passés, aujourd’hui en pleine intensité, le reste du cycle sous forme de barres projetées pâles à votre rythme récent, et une ligne en pointillés pour le rythme régulier qui tiendrait tout le cycle. Survolez-le ou donnez-lui le focus et utilisez les flèches du clavier pour lire n’importe quel jour.

Les limites sont un brouillon, comme dans toutes les autres sections de paramètres. Faites glisser le seuil d’alerte ou activez l’utilisation supplémentaire et les repères bougent aussitôt sur les compteurs, le compteur d’utilisation supplémentaire glisse en place et la barre d’enregistrement apparaît. Une limite inférieure à ce qui a déjà été dépensé pendant ce cycle est refusée avec le montant.

Les montées en gamme affichent la proratisation exacte avant tout prélèvement : le nouveau forfait pour les jours restants, les jours inutilisés de l’actuel, et « You’ll pay $13.33 today ». Les descentes attendent la fin de la période et listent ce qui disparaît. La résiliation se fait en une confirmation honnête sans offres, le forfait reste actif jusqu’à la fin de la période, et Keep Pro l’annule d’ici là.

Le formulaire de carte formate les numéros pendant la saisie sans déplacer le curseur, les vérifie avec Luhn, détecte la marque et valide l’expiration et le code de sécurité. Les factures ont des badges de statut, Pay now pour celles en échec, et se téléchargent en vrais fichiers PDF.

Installation

Ajouter le registre Pro à components.json

components.json

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

Ajouter votre token
Créez un token sur votre page de compte et placez-le dans .env.local sous le nom HEXTAUI_PRO_TOKEN.

Ajouter le block

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

Utilisation

Branchez-le à votre API

BillingSettings affiche les données que vous lui passez et vous rappelle à chaque changement. Retournez ou levez une erreur depuis un callback : un message levé s’affiche dans la boîte de dialogue qui l’a demandé, et rien ne change tant que vous ne passez pas de nouvelles props.

"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>
  )
}

Mises à jour de carte

onUpdatePaymentMethod reçoit les chiffres nettoyés, l’expiration, le code de sécurité et la marque une fois le formulaire validé. Levez une erreur pour afficher un refus dans la boîte de dialogue. En production, transmettez les informations à la tokenisation de votre prestataire de paiement et ne les stockez jamais vous-même.

"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.")
      }}
    />
  )
}

Vos propres fichiers de facture

Les factures se téléchargent en PDF construits dans le navigateur à partir des données de la facture. Retournez un Blob depuis onDownloadInvoice pour servir votre propre fichier à la place, ou donnez un href à une facture.

"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()
      }}
    />
  )
}

Anatomie

Les parties à composer, de l’extérieur vers l’intérieur.

Partie	Description
`BillingSettings`	Le contenu de la section : résumé du forfait, compteurs d’utilisation et Chart quotidien, limites, forfaits, paiement, factures et annulation, avec leurs boîtes de dialogue.
`BillingSettingsSkeleton`	Un placeholder de chargement à la forme de la section. Passez-le au skeleton de SettingsSection.
`prorate`	Le calcul de proratisation derrière la boîte de dialogue de montée en gamme, pour votre serveur ou vos tests.
`forecastUsage`	La projection derrière le compteur et la note d’épuisement.
`createInvoicePdf`	Construit le PDF de la facture sous forme de Blob.

Référence de l’API

BillingSettings

Les prix sont en centimes et les dates sont des jours ISO comme 2026-10-28. Omettez un callback pour masquer son action.

Prop	Type	Par défaut
`plans`{ id, name, price, included, description?, features }. Les features sont des listes complètes par forfait, donc une rétrogradation peut lister ce qui manque. Un forfait de price 0 est celui vers lequel les gens basculent quand ils résilient.	`BillingPlan[]`	`–`
`subscription`{ planId, periodStart, periodEnd, status?, cancelAtPeriodEnd?, scheduledPlanId? }.	`BillingSubscription`	`–`
`usage`{ models: { id, name, used }[], daily: { date, used }[], extraRate, unit? }. extraRate est en centimes par unité au-delà de ce qui est inclus. unit vaut "credits" par défaut.	`BillingUsage`	`–`
`spendLimit`{ enabled, limit, alertAt }. limit est en centimes et alertAt est un pourcentage.	`BillingSpendLimit`	`–`
`paymentMethod`{ brand, last4, expMonth, expYear, name? }.	`BillingPaymentMethod \| null`	`–`
`invoices`{ id, number, date, description, amount, status, href?, lines?, paidWith? }. status vaut paid, open, failed, refunded ou void.	`BillingInvoice[]`	`[]`
`today`Le jour que votre serveur considère comme aujourd’hui. Utilisé pour la proratisation, les projections et l’expiration des cartes, afin que le serveur et le navigateur concordent.	`string`	`the last daily date`
`currency`N’importe quel code de devise ISO.	`string`	`"USD"`
`seller`Le nom en haut des factures générées.	`string`	`"Hexta"`
`customer`Imprimé sous Bill to sur les factures générées.	`{ name?, email? }`	`–`
`onChangePlan`Appelé avec { planId, when, amountDue }. when vaut « now » pour les montées en gamme et « period_end » pour les descentes.	`(change) => void \| Promise`	`–`
`onCancelPlan`Annuler à la fin de la période.	`() => void \| Promise`	`–`
`onResumePlan`Annule une résiliation ou une rétrogradation programmée.	`() => void \| Promise`	`–`
`onSpendLimitChange`Enregistre les limites. Retournez { limit: message } pour afficher une erreur de champ.	`(limit) => void \| errors \| Promise`	`–`
`onUpdatePaymentMethod`Appelé avec { number, expMonth, expYear, cvc, name, brand } une fois le formulaire valide. Levez une erreur pour afficher un refus.	`(card) => void \| Promise`	`–`
`onPayInvoice`Ajoute Pay now aux factures ouvertes et échouées.	`(invoice) => void \| Promise`	`–`
`onDownloadInvoice`Retournez un Blob pour télécharger votre propre fichier, ou rien si vous l’avez géré. Sans cela, un PDF est construit à partir de la facture.	`(invoice) => Blob \| void \| Promise`	`–`

prorate

Renvoie { kind, amountDue, charge, credit, daysLeft, totalDays, effectiveDate, nextBillingDate }.

Prop	Type	Par défaut
`options`Les montées en gamme facturent la différence de prix pour les jours restants, arrondie une seule fois. Les descentes ne facturent rien et démarrent à periodEnd. Quitter un forfait gratuit facture un mois complet à partir d’aujourd’hui.	`{ from, to, periodStart, periodEnd, today }`	`–`

Clavier

Touche	Action
`←→`	Quand le graphique quotidien a le focus, déplace l’infobulle vers le jour précédent ou suivant.
`Enter`	Dans le formulaire de carte, vérifie les informations et enregistre.
`⌘S`	Enregistre les limites modifiées. Ctrl+S sous Windows et Linux.

Accessibilité

Les compteurs utilisent role meter avec un texte de valeur qui inclut la projection et le seuil d’alerte, et la répartition par modèle est une vraie liste.
Le graphique quotidien est une figure nommée « Daily usage this cycle », décrite par un résumé avec le total, la moyenne quotidienne récente, le jour le plus chargé et le rythme régulier. Un tableau masqué visuellement liste chaque jour, les jours projetés étant marqués comme des estimations.
Les changements de forfait, annulations, mises à jour de carte et téléchargements sont annoncés poliment. Les échecs s’affichent dans la boîte de dialogue qui les a demandés, sous forme d’alerte, et la boîte reste ouverte avec votre saisie.
Les champs de carte utilisent les tokens autocomplete standard, donc les navigateurs et les gestionnaires de mots de passe peuvent les remplir. Le premier champ invalide reçoit le focus.
Les champs de saisie font 16px sur les écrans tactiles pour que iOS ne zoome pas, et les boutons passent à 44px.
Les nombres et les dates sont formatés en anglais avec des fuseaux horaires fixes, donc le serveur et le navigateur affichent le même texte.

Construit avec

Les composants HextaUI gratuits dont Billing est constitué. Chacun s’installe séparément.

Code

4 fichiers, ajoutés à components/blocks/billing.