CreditBalance

CreditBalance shows how many credits a customer has in one credit system, and the grants and top-ups they come from. From React 0.11.0. When to use

Next to an AI or credit-metered feature, so customers see what is left.
The credits section of your billing settings, with CreditHistory below it.
Any place that shows what remains of each grant or top-up and when it expires.

CreditBalance with 1,240 AI credits from a plan grant and a top-up, light theme

Importing CreditBalance

import {
  CreditBalance,
  useCreditBalance,
  type CreditBalanceData,
  type CreditBalanceSource,
} from '@nozle-js/react'

Rendering CreditBalance

Inside a BillingProvider with billingEndpoint, read the balance with useCreditBalance and pass it in:

app/billing/credits/page.tsx

'use client'
import { BillingProvider } from '@nozle-js/react'

function AiCredits() {
  const { data, isPending, error } = useCreditBalance('ai_credits')
  return <CreditBalance balance={data} isLoading={isPending} error={error} />
}

export default function CreditsPage() {
  return (
    <BillingProvider publishableKey="pk_nozle_..." billingEndpoint="/api/nozle">
      <AiCredits />
    </BillingProvider>
  )
}

The card shows the available credits with the unit name, singular for exactly 1 (“1 credit available”, “1,240 credits available”), and “As of <date>” for the time of the reading. Below it, one line per source shows what remains and when it expires.

Data

balance is a CreditBalanceData. Credit amounts are decimal strings.

const balance: CreditBalanceData = {
  credit_system_name: 'AI credits',
  unit_name: 'credit',
  available: '1240',
  as_of: '2026-10-16T09:00:00Z',
  sources: [
    { id: 'grant_1', type: 'subscription_grant', remaining: '500', expires_at: '2026-11-01T00:00:00Z' },
    { id: 'topup_1', type: 'top_up', remaining: '740', expires_at: null },
  ],
}

export function Credits() {
  return <CreditBalance balance={balance} />
}

Live data

Inside a BillingProvider with billingEndpoint, useCreditBalance(creditSystemCode?) returns one balance of the signed-in customer: the given credit system, else the first one with credits, else the first one.

export function AiCredits() {
  const { data, isPending, error } = useCreditBalance('ai_credits')
  return <CreditBalance balance={data} isLoading={isPending} error={error} />
}

Without the hooks, pass one entry of the SDK’s credits.balance result, read on your backend.

Source types

Each source’s type sets its label. A source type the component does not know shows as sent. Sources whose remaining is "0" are hidden.

`type`	Label
`subscription_grant`	Plan grant
`top_up`	Top-up
`manual_grant`	Granted
`adjustment`	Adjustment
`allocated_top_up`	Allocated top-up

Examples

Loading, empty and error

isLoading shows a loading placeholder, no balance shows emptyMessage, and error shows the message as an alert.

CreditBalance loading placeholder, No credit balance yet message, and an error message, light theme

export function BalanceStates() {
  return (
    <>
      <CreditBalance isLoading />
      <CreditBalance balance={null} />
      <CreditBalance error="Credits could not be loaded." />
    </>
  )
}

API reference

CreditBalanceData | null

null or no value shows the empty message.

Show properties

string

required

Heading of the card.

string

required

Singular unit name, for example credit. An s is added unless available is exactly 1.

string

required

Credits available, as a decimal string.

string

required

Time of the reading, shown as “As of <date>”.

CreditBalanceSource[]

Where the credits come from: id, type, remaining and expires_at. See Source types.

boolean

default:false

Shows a loading placeholder.

Error | string | null

Shows the message as an alert. Defaults to null.

string

default:"No credit balance yet."

Shown when there is no balance.

Appearance

Theme, variables and element overrides. Defaults to the provider’s. See Appearance.

Dates show in en-US (“Oct 16, 2026”).

States

State	What shows
`isLoading`	A skeleton placeholder with `role="status"`.
`error` set	The message in a `role="alert"` card, in the danger text colour.
No `balance`	`emptyMessage`.

Appearance

Element keys

creditBalance (root), creditBalance__amount (the large number).Style them with appearance.elements. See Elements.

CreditHistory

How credits were used and granted.

Credits

How credit systems work.

Setup

Components

Billing

Entitlements

CreditBalance

Importing CreditBalance

Rendering CreditBalance

Data

Live data

Source types

Examples

Loading, empty and error

API reference

States

Appearance

CreditHistory

Credits

​Importing CreditBalance

​Rendering CreditBalance

​Data

​Live data

​Source types

​Examples

​Loading, empty and error

​API reference

​States

​Appearance

​Related

CreditHistory

Credits

Importing CreditBalance

Rendering CreditBalance

Data

Live data

Source types

Examples

Loading, empty and error

API reference

States

Appearance

Related