UsageTrend

UsageTrend draws one bar per past billing period, oldest first, labelled with the period’s start date and its amount or units. From React 0.11.0. When to use

A usage history section of your billing settings.
Beside UsageBreakdown to compare this period with earlier ones.
A chart of one feature’s units over time, with featureCode.

UsageTrend with five monthly bars from $7.20 to $17.32, light theme

Importing UsageTrend

import {
  UsageTrend,
  useUsage,
  type CustomerUsageData,
} from '@nozle-js/react'

Rendering UsageTrend

Inside a BillingProvider with billingEndpoint, read past periods with useUsage({ period: 'past' }) and pass them in:

app/billing/history/page.tsx

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

function History() {
  const { data, isPending, error } = useUsage({ period: 'past', periods: 6 })
  return <UsageTrend periods={data} isLoading={isPending} error={error} />
}

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

Periods can come in any order; they are sorted by start date. Bars scale to the largest period, and each bar has an accessible label with its date and value. Dates show in UTC in en-US.

Data

periods is a list of CustomerUsageData, one per billing period, as in the usage_periods of Core’s past-usage endpoint. Amounts are in cents; units is a decimal string.

const period = (from: string, to: string, apiCalls: number): CustomerUsageData => ({
  from_datetime: from,
  to_datetime: to,
  currency: 'USD',
  amount_cents: Math.round(apiCalls * 0.04),
  charges_usage: [
    {
      units: String(apiCalls),
      amount_cents: Math.round(apiCalls * 0.04),
      amount_currency: 'USD',
      charge: { nozle_id: `chg_${from}`, charge_model: 'standard' },
      feature: { nozle_id: 'ftr_api', code: 'api_calls', name: 'API calls' },
    },
  ],
})

const periods: CustomerUsageData[] = [
  period('2026-08-01T00:00:00Z', '2026-08-31T23:59:59Z', 26400),
  period('2026-09-01T00:00:00Z', '2026-09-30T23:59:59Z', 29800),
]

export function History() {
  return <UsageTrend periods={periods} />
}

Full example data

const period = (from: string, to: string, apiCalls: number): CustomerUsageData => ({
  from_datetime: from,
  to_datetime: to,
  currency: 'USD',
  amount_cents: Math.round(apiCalls * 0.04),
  charges_usage: [
    {
      units: String(apiCalls),
      amount_cents: Math.round(apiCalls * 0.04),
      amount_currency: 'USD',
      charge: { nozle_id: `chg_${from}`, charge_model: 'standard' },
      feature: { nozle_id: 'ftr_api', code: 'api_calls', name: 'API calls' },
    },
  ],
})

const periods: CustomerUsageData[] = [
  period('2026-07-01T00:00:00Z', '2026-07-31T23:59:59Z', 22100),
  period('2026-08-01T00:00:00Z', '2026-08-31T23:59:59Z', 26400),
  period('2026-09-01T00:00:00Z', '2026-09-30T23:59:59Z', 29800),
]

export function History() {
  return (
    <>
      <UsageTrend periods={periods} />
      <UsageTrend periods={periods} featureCode="api_calls" />
    </>
  )
}

Live data

useUsage({ period: 'past' }) reads past periods for the signed-in customer through your billingEndpoint; periods sets how many. Its data is the list of periods and passes to periods directly:

export function LiveTrend() {
  const { data, isPending, error } = useUsage({ period: 'past', periods: 6 })
  return <UsageTrend periods={data} isLoading={isPending} error={error} />
}

Without the hooks, read GET https://api.nozle.app/core/api/v1/customers/{external_customer_id}/past_usage on your backend with a secret key and pass its usage_periods. It takes periods_count and feature_code.

Examples

Units of one feature

With featureCode, each bar shows that feature’s units in the period instead of the amount, for example “29,800 api_calls”. Periods without the feature show zero.

UsageTrend with the API call units of five months, light theme

export function ApiCallsTrend() {
  const { data, isPending, error } = useUsage({ period: 'past', periods: 6 })
  return <UsageTrend periods={data} featureCode="api_calls" isLoading={isPending} error={error} />
}

Loading, empty and error

isLoading shows a loading placeholder, an empty list shows emptyMessage, and error shows the message as an alert.

UsageTrend loading placeholder, No past usage yet message, and an error message, light theme

export function TrendStates() {
  return (
    <>
      <UsageTrend isLoading />
      <UsageTrend periods={[]} />
      <UsageTrend error="Usage history could not be loaded." />
    </>
  )
}

API reference

CustomerUsageData[] | null

The periods to chart, in any order. Empty or missing shows the empty message.

string

Charts the units of this feature instead of the amount. Bars read “29,800 api_calls”.

boolean

default:false

Shows a loading placeholder.

Error | string | null

Shows the message as an alert. Defaults to null.

string

default:"No past usage yet."

Shown when there are no periods.

Appearance

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

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 periods	`emptyMessage`.

Appearance

Element keys

usageTrend (root), usageTrend__bar (each bar).Style them with appearance.elements. See Elements.

UsageBreakdown

This period’s units and amounts.

UsageDashboard

Usage against limits.

Setup

Components

Billing

Entitlements

Importing UsageTrend

Rendering UsageTrend

Data

Live data

Examples

Units of one feature

Loading, empty and error

API reference

States

Appearance

UsageBreakdown

UsageDashboard

​Importing UsageTrend

​Rendering UsageTrend

​Data

​Live data

​Examples

​Units of one feature

​Loading, empty and error

​API reference

​States

​Appearance

​Related

UsageBreakdown

UsageDashboard

Importing UsageTrend

Rendering UsageTrend

Data

Live data

Examples

Units of one feature

Loading, empty and error

API reference

States

Appearance

Related