Provider and hooks

The data hooks are built on TanStack Query v5, a peer dependency:

npm install @nozle-js/react@0.11.0 @tanstack/react-query@5

Requires @nozle-js/react 0.11.0 and a backend on @nozle-js/node 0.13.0. usePlans reads the public plan catalog with the publishable key. The customer hooks read the signed-in customer’s billing data from a route on your own backend, so the browser never holds a secret key and can only see its own customer.

Customer hooks

Serve the hooks from your backend

createBillingHandler from @nozle-js/node is a web-standard request handler that serves every customer hook with your secret key. The customer always comes from getCustomerId, read from your session; a customer id sent by the browser is ignored.

app/api/nozle/[route]/route.ts

import { auth } from '@/lib/auth'
import { Nozle, createBillingHandler } from '@nozle-js/node'

const nozle = new Nozle() // reads NOZLE_SECRET_KEY

export const GET = createBillingHandler(nozle, {
  getCustomerId: async (request) => (await auth(request))?.workspaceId,
})

The last path segment picks the route: subscription, entitlement, credits, credit-history, usage, preview, invoices or invoice-download. invoices lists only the signed-in customer’s finalized invoices, and invoice-download answers 404 for an invoice of another customer. The handler answers 401 without a customer, passes Nozle’s 4xx errors through with their code, and answers 502 billing_unavailable for upstream failures without internal detail. It runs in Next.js route handlers, Hono, Remix, Bun and Deno. Then point the provider at it:

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

<BillingProvider
  publishableKey="pk_..."
  billingEndpoint="/api/nozle"
  billingHeaders={() => ({ 'X-CSRF-Token': csrfToken })}
>
  {children}
</BillingProvider>

billingHeaders adds headers such as a CSRF token. Pass your app’s queryClient to share its cache and devtools; without one the provider makes its own. The hooks pass their client explicitly and never replace your app’s QueryClientProvider.

The hooks

Each hook returns TanStack Query’s result (data, isPending, error, refetch and the rest).

Hook	`data`	Use with
`useSubscription()`	`{ subscription, pending_change, past_due }`: plan, status, `ending_at`, a scheduled change, and `past_due` when an invoice is unpaid past its due date; nulls without a subscription	An “upgrade” or “ends on” banner
`useEntitlement(featureCode)`	`allowed`, `used`, `limit`, `remaining` (the `can()` result)	`FeatureGate`, `UsageMeter`
`useCreditBalance(creditSystemCode?)`	One balance: the given credit system, else the first with credits	`<CreditBalance balance={data} />`
`useCreditHistory({ creditSystemCode?, limit? })`	Paged operations; `operations` flattens the loaded pages	`<CreditHistory operations={operations} hasMore={hasNextPage} onLoadMore={fetchNextPage} />`
`useUsage({ period })`	`period: "current"` (default): this period’s usage, `CustomerUsageData \| null`; `"past"`: past periods, `CustomerUsageData[]` (`periods` sets how many)	`<UsageBreakdown usage={data} />` with `useUsage()`, `<UsageTrend periods={data} />` with `useUsage({ period: "past" })`; no cast needed
`useUpgradePreview(planCode)`	The price of changing to `planCode`, now and at the effective date; waits until a plan is given	A confirm step before a plan change
`useInvoices({ page })`	`{ invoices, meta }`: the customer’s finalized invoices, newest first, 20 per page	An invoice history table
`useInvoiceDownload()`	A function `(invoiceId) => Promise<string \| null>`: the PDF URL, or `null` while Nozle is still generating it	A download button

useBillingRefresh() returns a function that reloads every billing hook, for example after checkout or a plan change.

import { CreditBalance, useCreditBalance, useEntitlement } from '@nozle-js/react'

function AiPanel() {
  const credits = useCreditBalance()
  const entitlement = useEntitlement('ai_calls')
  if (entitlement.data && !entitlement.data.allowed) return <p>Upgrade to keep using AI.</p>
  return <CreditBalance balance={credits.data} isLoading={credits.isPending} error={credits.error} />
}

A failed request throws BillingRequestError with status, code and requestId. A 4xx is not retried; other failures are retried twice. For subscription changes with confirmation and recovery, use the billing portal action adapters.

`usePlans`

Fetches GET /api/v1/plans through the BillingProvider catalog client. Calls share one cached request per publishableKey and baseUrl, kept for five minutes. A failed load is not retried automatically; call refetch(). usePlans does not fetch during server rendering; it renders the initial loading state.

import { usePlans } from '@nozle-js/react'

function PlanList() {
  const { plans, isLoading, error } = usePlans()

  if (isLoading) return <p>Loading plans…</p>
  if (error) return <p role="alert">Plans could not be loaded: {error.message}</p>

  return plans.map((plan) => (
    <div key={plan.code}>
      {plan.name}: {plan.amount_currency} {plan.amount_cents / 100}
    </div>
  ))
}

Return value

Field	Type	Description
`plans`	`CatalogPlan[]`	Every plan of the organization, as the catalog returns it. See what the type declares.
`isLoading`	`boolean`	`true` until the catalog request settles.
`error`	`Error \| null`	Set when the request fails: `HTTP <status>` (for example `HTTP 500`) or the thrown message, such as `Failed to fetch`. `plans` is `[]`.
`refetch`	`() => Promise`	Loads the catalog again.

`CatalogPlan`: type versus runtime

The TypeScript type CatalogPlan declares code, name, amount_cents, amount_currency and interval, and the optional description (string | null), entitlements, credit_grant_rules and charges. Its plans pass to PricingTable, PlanCard and PlanComparison as they are. At runtime, each item in plans is the trimmed plan object the API returns to a publishable key. usePlans does not remove or rename fields. Besides the declared fields, a plan carries nozle_id, trial_period, pay_in_advance, usage_thresholds, taxes, credit_pool_policies, and metadata when set. Invoice names, internal ids, margin settings, grant policies and timestamps are not sent to a publishable key. See the public plan catalog for every field. The list is not filtered. It includes trial plans and pay-in-arrears plans, and not plans that are pending deletion. Decide in your component which plans to show. To read an undeclared field, widen the type:

import type { CatalogPlan } from '@nozle-js/react'

type CatalogPlanDetail = CatalogPlan & {
  trial_period?: number | null
  pay_in_advance?: boolean
}

function useNonTrialPlans() {
  const { plans, isLoading, error } = usePlans()
  const nonTrial = (plans as CatalogPlanDetail[]).filter((plan) => plan.trial_period == null)
  return { plans: nonTrial, isLoading, error }
}

The publishable key is public, so every field it receives, including charges, taxes, minimums, credit grants and metadata, is readable by anyone who has it. Do not put sensitive or negotiated pricing in plans of an organization whose publishable key you ship. See Keep sensitive pricing out of the catalog.

`useCheckoutSession`

Calls BillingProvider.createCheckout with a plan code and return URL.

import { Checkout, useCheckoutSession } from '@nozle-js/react'

function BuyProButton() {
  const { fetchClientSecret, checkout, isLoading, error } = useCheckoutSession()

  async function startCheckout() {
    const clientSecret = await fetchClientSecret(
      'pro',
      'https://app.example.com/settings/billing',
    )

    if (clientSecret) {
      // Render <Checkout clientSecret={clientSecret} ... />
    }
  }

  return (
    <>
      <button disabled={isLoading} onClick={() => void startCheckout()}>
        {isLoading ? 'Starting…' : 'Choose Pro'}
      </button>
      {error && <p role="alert">{error.message}</p>}
      {checkout && 'type' in checkout && checkout.type === 'scheduled' && (
        <p>Your change is scheduled.</p>
      )}
    </>
  )
}

fetchClientSecret passes only planCode and returnUrl to createCheckout. It sends no idempotency key; use CheckoutButton when you need one. The hook returns a string only for a Stripe client secret. For a hosted result (or a result with a url), it navigates to the URL and returns null. For completed, scheduled, razorpay, and processing results it returns null without opening Razorpay or polling; read the result from checkout and handle it yourself, for example with Checkout’s checkout prop. Any other result throws Checkout response did not include a supported result type.

Return value

Field	Type	Description
`fetchClientSecret`	`(planCode, returnUrl?) => Promise<string \| null>`	Starts checkout and returns an embedded Stripe secret when present.
`checkout`	`CheckoutResult \| null`	Most recent raw checkout result.
`isLoading`	`boolean`	Whether checkout creation is in progress.
`error`	`Error \| null`	Most recent checkout error.

`useBillingContext`

Returns the required billing context and throws outside BillingProvider.

import { useBillingContext } from '@nozle-js/react'

const { client, createCheckout, verifyCheckout, getCheckoutStatus } = useBillingContext()

Use this only when building a custom catalog or checkout component. Prefer usePlans and useCheckoutSession for common flows.

`useOptionalBillingContext`

Returns the billing context or null outside a provider. PricingTable uses this behavior so caller-supplied plans can render without a catalog provider.

`useNozleClient`

Returns the browser-safe NozleClient:

import type { NozleClient } from '@nozle-js/react'

interface NozleClient {
  publishableKey: string
  baseUrl: string
  catalogFetch(path: string, init?: RequestInit): Promise<Response>
}

catalogFetch is for public catalog endpoints only. Do not use it to proxy customer billing requests.

`BillingContext`

BillingContext is exported for advanced integrations that need React’s direct context API. Its value is either null or:

import type { CreateCheckout, GetCheckoutStatus, VerifyCheckout } from '@nozle-js/react'

interface BillingContextValue {
  client: NozleClient
  createCheckout?: CreateCheckout
  verifyCheckout?: VerifyCheckout
  getCheckoutStatus?: GetCheckoutStatus
}

Prefer useBillingContext or useOptionalBillingContext in application components so missing-provider behavior stays explicit.

Checkout result types

createCheckout returns the result your merchant backend received from Nozle. It may be:

Result	Shape	Component behavior
Stripe	`{ type: 'stripe', client_secret }` (also `clientSecret`)	Plan and invoice checkout return an embedded Checkout Session client secret (`cs_`), never a Stripe URL. `CheckoutButton` passes it to `onStripeClientSecret`.
Razorpay	`{ type: 'razorpay', checkout_id, key_id, order_id, amount_cents, currency }`	Loads `https://checkout.razorpay.com/v1/checkout.js`, calls `verifyCheckout`, then polls `getCheckoutStatus`.
Hosted	`{ type: 'hosted', payment_url }`	Redirects with `location.assign`. The URL must use HTTPS. `POST /checkout` never returns it for Razorpay, so your `createCheckout` only sees it if your backend forwards a payment link.
Processing	`{ type: 'processing', checkout_id, status }`	Polls `getCheckoutStatus`, which is required. Razorpay returns it while an order is not ready or after it expired, and Stripe returns it for a replayed quoted upgrade whose webhook is still pending.
Completed	`{ type: 'completed', ... }`	Calls `onComplete`.
Scheduled	`{ type: 'scheduled', ... }`	Calls `onScheduled`.

Razorpay fields are snake case. A { type: 'razorpay', orderId } result fails: useCheckoutSession returns null, and CheckoutButton shows Razorpay checkout requires server-issued checkout_id, key_id and order_id. Polling calls getCheckoutStatus up to 30 times, one second apart, until both status and fulfillment_status are succeeded.

Error	Cause
`Checkout URL must use HTTPS`	A `hosted` `payment_url` (or `url`) is not HTTPS.
`Checkout response did not include a supported result type`	`useCheckoutSession` received an unknown result.
`onStripeClientSecret is required for embedded Stripe checkout`	`CheckoutButton` received a Stripe client secret without the callback.

The components also accept { type: 'stripe', url } and a legacy { url }, and redirect to them. Plan and invoice checkout do not return either; they return a client secret. Stripe webhooks remain authoritative. A browser redirect or completion callback does not activate a paid plan by itself.

Setup

Components

Billing

Entitlements

Provider and hooks

Customer hooks

Serve the hooks from your backend

The hooks

`usePlans`

Return value

`CatalogPlan`: type versus runtime

`useCheckoutSession`

Return value

`useBillingContext`

`useOptionalBillingContext`

`useNozleClient`

`BillingContext`

Checkout result types

​Customer hooks

​Serve the hooks from your backend

​The hooks

​usePlans

​Return value

​CatalogPlan: type versus runtime

​useCheckoutSession

​Return value

​useBillingContext

​useOptionalBillingContext

​useNozleClient

​BillingContext

​Checkout result types

Customer hooks

Serve the hooks from your backend

The hooks

`usePlans`

Return value

`CatalogPlan`: type versus runtime

`useCheckoutSession`

Return value

`useBillingContext`

`useOptionalBillingContext`

`useNozleClient`

`BillingContext`

Checkout result types