Installation

npm install @nozle-js/react react react-dom @stripe/stripe-js @stripe/react-stripe-js

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, choose a Nozle customer, or call customer billing APIs directly.

Configure `BillingProvider`

Wrap billing UI in BillingProvider. 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 { BillingProvider, PricingTable } from '@nozle-js/react'

export function BillingPage({ csrfToken }: { csrfToken: string }) {
  return (
    <BillingProvider
      publishableKey={import.meta.env.VITE_NOZLE_PUBLISHABLE_KEY}
      baseUrl="https://api.nozle.app"
      createCheckout={async ({ planCode, returnUrl }) => {
        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 }),
        })

        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.
`baseUrl`	`string`	`https://api.nozle.app`	Nozle API origin used for public catalog requests.
`children`	`ReactNode`	required	Components that consume the billing context.

BillingProvider throws when publishableKey does not begin with pk_.

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

All interactive exports are client components. In Next.js App Router, render the provider and interactive SDK components from a file containing "use client". Customer billing status, invoices, subscriptions, cancellation, credits, usage, and entitlements must come from your authenticated backend. Pass that returned state into components such as FeatureGate, UsageMeter, and PlanBadge.

Never expose an sk_, master key, customer session, or internal credential in a browser bundle. CORS and Origin headers are not authentication.

Next steps

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

Setup

Billing

Entitlements

Installation

Configure `BillingProvider`

Provider props

Implement the merchant endpoint

Framework notes

Next steps

​Configure BillingProvider

​Provider props

​Implement the merchant endpoint

​Framework notes

​Next steps

Configure `BillingProvider`

Provider props

Implement the merchant endpoint

Framework notes

Next steps