> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the React SDK and configure public catalog reads with merchant-backed checkout.

```bash theme={null}
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_`.

```tsx theme={null}
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:

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

See [Merchant backend billing](/guides/getting-started/merchant-backend-bff) 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`.

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

## Next steps

* Browse [components](/sdks/react/components).
* Use the [provider hooks](/sdks/react/hooks).
* Add [feature gates](/sdks/react/gates).
* Match the components to your product with [theming](/sdks/react/styling).