Installation

npm install @nozle-js/react@0.11.0 @tanstack/react-query react react-dom @stripe/stripe-js @stripe/react-stripe-js

Version 0.11.0 defaults catalog requests to https://api.nozle.app/engine. Peer dependencies are @tanstack/react-query 5 or later (required from 0.11.0), react and react-dom 18 or later, @stripe/react-stripe-js 3 or later, and @stripe/stripe-js 5 or later. Install the Stripe packages even if you only use PricingTable or BillingPortal: without them the import fails with ERR_MODULE_NOT_FOUND. The React SDK has two browser-safe responsibilities:

read the public plan catalog with a publishable pk_ key; and
render checkout and billing UI using data or callbacks supplied by your application.

It does not accept a secret key or choose a Nozle customer. The native billing portal uses customer-scoped GraphQL reads using a session issued by your backend; it never uses your secret key in the browser.

BillingPortal, CancellationControl, PlanChangeControl, and their self-service adapters are included from 0.10.2. Use Node 0.10.0, Python 0.10.0, or Go v0.9.1 or later on your merchant backend. The billing hooks need React 0.11.0 with a backend on Node 0.13.0. See Billing portal and self-service for setup.

Configure `BillingProvider`

Wrap public catalog and provider-context checkout UI in BillingProvider. BillingPortal and its management controls use their own callbacks and do not require this provider. Your createCheckout callback calls an authenticated merchant endpoint; that endpoint derives the customer from the logged-in user or team and calls Nozle with a restricted sk_.

import { Nozle } from '@nozle-js/node'
import { BillingProvider, PricingTable } from '@nozle-js/react'

const nozle = new Nozle() // reads NOZLE_SECRET_KEY

export function BillingPage({ csrfToken }: { csrfToken: string }) {
  return (
    <BillingProvider
      publishableKey={import.meta.env.VITE_NOZLE_PUBLISHABLE_KEY}
      baseUrl="https://api.nozle.app/engine"
      createCheckout={async ({ planCode, returnUrl, idempotencyKey }) => {
        const response = await fetch('/api/billing/checkout', {
          method: 'POST',
          credentials: 'include',
          headers: {
            'Content-Type': 'application/json',
            'X-CSRF-Token': csrfToken,
          },
          body: JSON.stringify({ planCode, returnUrl, idempotencyKey }),
        })

        if (!response.ok) throw new Error('Checkout failed')
        return response.json()
      }}
    >
      <PricingTable returnUrl="https://app.example.com/settings/billing" />
    </BillingProvider>
  )
}

Provider props

Prop	Type	Default	Description
`publishableKey`	`string`	required	Browser-safe key beginning with `pk_`.
`createCheckout`	`(input) => Promise<CheckoutResult>`	—	Merchant callback used by checkout components.
`verifyCheckout`	`(checkoutId, verification) => Promise<CheckoutStatus>`	—	Merchant callback that verifies a Razorpay payment. Required for Razorpay results.
`getCheckoutStatus`	`(checkoutId) => Promise<CheckoutStatus>`	—	Merchant callback that returns checkout status. Required for `processing` results, and for Razorpay when verification returns a status that has not yet succeeded.
`baseUrl`	`string`	`https://api.nozle.app/engine`	Nozle API origin used for public catalog requests.
`billingEndpoint`	`string`	—	Path of your backend route that serves the billing hooks, for example `/api/nozle`. Serve it with `createBillingHandler` from `@nozle-js/node`.
`billingHeaders`	`() => HeadersInit \| Promise<HeadersInit>`	—	Extra headers for billing endpoint requests, such as a CSRF token.
`queryClient`	`QueryClient`	A client the provider makes	Your app’s TanStack Query client, to share its cache. The hooks never use or replace your `QueryClientProvider`.
`appearance`	`Appearance`	Light theme	Theme, variables and elements for every component inside. See Appearance.
`savedAppearance`	`boolean`	`true`	Set `false` to ignore the appearance saved in the dashboard (Developers > Customize SDK). Requires `0.13.0`. See Saved appearance.
`children`	`ReactNode`	required	Components that consume the billing context.

BillingProvider throws when publishableKey does not begin with pk_.

`createCheckout` input

Caller	Fields passed
`CheckoutButton`	`idempotencyKey`, `planCode`, `returnUrl`, plus `registerMandate` when set
`useCheckoutSession`, `PricingTable`	`planCode`, `returnUrl` only, with no idempotency key

subscriptionId and quoteId are passed only by UpgradeButton and UpgradeModal.

Implement the merchant endpoint

The merchant endpoint must:

authenticate the application user;
derive the Nozle customer from server-owned user or team data;
reject browser-provided customer identifiers;
validate the requested plan and exact HTTPS return origin; and
call Nozle with a least-privilege sk_.

See Merchant backend billing for a complete route.

Framework notes

The published bundle has no "use client" directive. In a Next.js App Router server component, import the SDK in your own client component (a file starting with "use client") and render that instead. Both the ESM and CJS builds load in Node, and renderToString works for PricingTable and BillingPortal. Customer state for presentational components comes from your authenticated backend. Pass it into FeatureGate, UsageMeter, and PlanBadge, from your own route or from the billing hooks when you set billingEndpoint. CurrentPlan reads the billing hooks itself. The native portal instead obtains a customer-scoped session from that backend for its Core GraphQL requests; management actions still go through your authenticated merchant endpoints.

Never embed an sk_, master key, portal session token, or internal credential in a static browser bundle. Return scoped portal tokens only at runtime to the authenticated customer. CORS and Origin headers are not authentication.

Next steps

Add the native billing portal.
Browse components.
Use the provider hooks.
Add feature gates.
Match the components to your product with theming.

Setup

Components

Billing

Entitlements

Installation

Configure `BillingProvider`

Provider props

`createCheckout` input

Implement the merchant endpoint

Framework notes

Next steps

​Configure BillingProvider

​Provider props

​createCheckout input

​Implement the merchant endpoint

​Framework notes

​Next steps

Configure `BillingProvider`

Provider props

`createCheckout` input

Implement the merchant endpoint

Framework notes

Next steps