# Monetize.software — SDK 3.0 Integration Pack (for AI coding agents)

This is a focused, single-file documentation pack for **Monetize.software SDK 3.0**.
It is designed to be fed to an AI coding agent (Cursor, Claude Code, Copilot, etc.)
together with a short task brief from the integrator.

**What's inside this file**

- Full SDK 3.0 reference: `AuthClient`, `BillingClient`, `PaywallUI`, `ApiGatewayClient`,
  bootstrap, events, errors, storage adapters, locale, security model.
- Three end-to-end integration guides: Web (SPA), Chrome Extension (MV3), Headless (server / custom UI).
- Paywall features (covered inside the SDK reference): anonymous sign-in, trial,
  tokenization (API Gateway), translations/locale, local pricing (via bootstrap).
- Setup context that affects code: custom domains (apiOrigin), webhooks (events for your backend).

---

## How to use this file (instructions for the agent)

The integrator will tell you:

1. **`paywallId`** — numeric ID from their dashboard (Paywalls → URL).
2. **`apiOrigin`** — their custom domain, e.g. `https://billing.theirapp.com`.
   This is **REQUIRED** at SDK init and has no fallback.
3. **Channel** — one of: `web` (SPA), `extension` (Chrome MV3), `headless` (server / custom UI).
4. **(optional)** `providerId` — UUID, if they use API Gateway for metered AI calls.
5. **(optional)** Auth requirements — login needed? Which OAuth providers?

### Hard rules — do not violate

1. `apiOrigin` is required. Never default to `https://appbox.space`, `https://monetize.software`,
   or any other host. If the integrator didn't give you one, **ask**.
2. SDK 3.0 is **bundled npm only**. There is no CDN/script-tag distribution
   (CWS policy for extensions, and it's the only supported channel for web/headless too).
   Do not write `<script src="...">` tags pointing at any CDN — use `pnpm add` / `npm i`.
3. Web/headless ⇒ `@monetize.software/sdk` (or `@monetize.software/sdk/core` for headless without UI).
   Chrome extension (MV3) — pick by which contexts touch billing:
     - Untrusted content scripts (run on third-party sites) OR billing in the service worker
       ⇒ `@monetize.software/sdk-extension` (offscreen document, one shared instance).
     - Only privileged extension-origin pages (popup / side panel / full-page tab / options)
       ⇒ `@monetize.software/sdk` directly, one instance per surface. They share
       `chrome.storage.local` (auto-detected) and sync via `chrome.storage.onChanged`.
       Do NOT pass a custom `storage` adapter — the SDK already resolves it.
4. For web with built-in login, use `new PaywallUI({ paywallId, apiOrigin, auth: true })`.
   Do not build your own login UI unless the integrator explicitly asks.
5. Headless / server contexts: pass `userId` (stable external ID). **Never** pass `userId` from
   browser code — it bypasses auth and will produce a runtime warning. In browser, use `auth`.
6. Listen to `purchase_completed` on the client to unlock the feature immediately. For durable
   state, also handle the corresponding webhook on your backend (see Webhooks section).

### Recommended integration flow (per channel)

- **Web (SPA)**:
  1. `pnpm add @monetize.software/sdk`
  2. Create one `PaywallUI({ paywallId, apiOrigin, auth: true })` per page/app.
  3. Call `paywall.open()` from the upgrade button.
  4. Subscribe to `purchase_completed`, `authChange`, `userChange`.
  5. (optional) Use `paywall.preload()` after initial render to warm bootstrap.

- **Chrome Extension (MV3) — content scripts on third-party sites, or billing in the SW**:
  1. `pnpm add @monetize.software/sdk-extension preact`
  2. Add `"offscreen"` and `"storage"` permissions to `manifest.json`.
     `host_permissions` for the apiOrigin is OPTIONAL — the API sends `ACAO: *` and the
     SDK fetches with `credentials: 'omit'`, so plain CORS handles it. Add it only as a
     CORS hedge; never `<all_urls>`.
  3. Wire `installRouter()` in the service worker and `startOffscreenServer()` in offscreen.
  4. Use the **same** `PaywallUI` API in popup/content-scripts — it proxies through chrome ports.

- **Chrome Extension (MV3) — privileged pages only (popup / side panel / full-page tab / options)**:
  1. `pnpm add @monetize.software/sdk` — no offscreen package, no `"offscreen"` permission (keep `"storage"`).
  2. `new PaywallUI({ paywallId, apiOrigin, auth: true })` once per surface; reach `paywall.billing` / `paywall.auth`.
     For metered AI calls, build `BillingClient` yourself and call `billing.createApiGatewayClient()`.
  3. Do **not** pass a `storage` adapter — `chrome.storage.local` is auto-detected and shared across these pages
     (sync via `chrome.storage.onChanged`). Writing a custom `chrome.storage` adapter just re-implements the built-in.
  4. Tradeoff: each surface refreshes/bootstraps on its own; if many are open at once, prefer the offscreen variant.

- **Headless (server / custom UI)**:
  1. `pnpm add @monetize.software/sdk`
  2. Import from `@monetize.software/sdk/core` (no UI / no Preact).
  3. `AuthClient` + `BillingClient` for billing; `ApiGatewayClient` for metered AI calls.
  4. Pass `userId` from your trusted backend. Handle `QuotaExceededError` explicitly.

### What you must produce as the agent

After reading this file, propose:

1. A short integration plan (which files you'll create/edit, where the SDK init lives).
2. The actual code changes for the chosen channel.
3. If subscription state must persist server-side: a webhook handler stub for the relevant events.

If anything is ambiguous (channel, auth, server-side persistence), ask the integrator
**before** writing code. Do not guess paywall IDs or origins.

---

## Source

Generated from MDX at https://monetize.software/docs-v2/sdk-v3 — for the same docs in the browser,
visit the URLs printed in each section header below.

Generated: 2026-06-25T12:43:50.676Z

---

# Authentication

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth

`AuthClient` is the SDK 3.0 sign-in client: email+password, OTP code, OAuth (Google/Apple/...), password reset, and anonymous sessions. It persists the session locally (localStorage / `chrome.storage.local` / memory), refreshes the access token on a timer, and emits `onAuthChange` on login, refresh, and logout.

```ts

const auth = new AuthClient({ paywallId: 'pw_123' });
await auth.ready(); // wait for session hydration from storage

if (auth.getCachedUser()) {
  // user is already signed in from a previous session
}
```

## Principles

- **Single source of truth** for the session — `AuthClient`. Any `BillingClient` accepts it as an option and automatically attaches `Authorization: Bearer <access>` to every API request, plus syncs `identity` from `auth.user`.
- **Default persistence** — `localStorage` on web, `chrome.storage.local` on extensions (auto-detected), in-memory as a fallback. You can supply your own `StorageAdapter`.
- **Lazy refresh.** `getAccessToken()` refreshes itself when expiry is less than 60s away. A network error returns the current token (still valid); a 401 on refresh signs the user out (refresh token revoked).
- **Refresh deduplication.** Parallel `getAccessToken()` calls share a single inflight refresh request to the backend.

  **No cookies.** SDK 3.0 is deliberately built around Bearer tokens so the same code runs in a Chrome extension, Telegram Mini App and a regular browser without juggling `SameSite`/`partitioned` cookies.

## Sign-in methods

- [Email & password](/docs-v2/sdk-v3/auth/email-password) — Classic signIn / signUp with password and email-confirmation handling

- [Email OTP](/docs-v2/sdk-v3/auth/otp) — Sign in / sign up with one email — 6-digit code via mail

- [Password reset](/docs-v2/sdk-v3/auth/password-reset) — Recovery email + new password via AuthClient

- [OAuth](/docs-v2/sdk-v3/auth/oauth) — Google, Apple, GitHub, Facebook via popup with PKCE

- [Anonymous sign-in](/docs-v2/sdk-v3/auth/anonymous) — signInAnonymously, resume after signOut, upgradeAnonymousToEmail

- [Session management](/docs-v2/sdk-v3/auth/session) — onAuthChange, signOut, refresh, manual getAccessToken

## API at a glance

      Method
      What it does
      Returns

      `signInWithEmail({email, password})`
      Sign in with password
      `AuthSession`

      `signUp({email, password})`
      Sign up. With email-confirm enabled returns `confirmation_required` without a session
      `SignUpResult`

      `sendOtp({email})`
      Sends a 6-digit code to the email
      `void`

      `verifyOtp({email, token, type?})`
      Verifies the code → session
      `AuthSession`

      `requestPasswordReset({email})`
      Recovery email with a code
      `void`

      `updatePassword({password})`
      Updates the password of the signed-in user
      `void`

      `signInWithOAuth({provider})`
      OAuth via popup with PKCE
      `AuthSession`

      `startOAuthFlow({provider})` / `completeOAuthFlow({state, code})`
      Low-level split of `signInWithOAuth` for offscreen-architecture (used by `@monetize.software/sdk-extension`). Most hosts call `signInWithOAuth` instead.
      `{authorize_url, state}` / `AuthSession`

      `signInAnonymously({captchaToken?, userMeta?, forceNewAnon?})`
      Anonymous sign-in. Idempotent + resumes the same anon user via stored refresh-token. Parallel calls dedupe.
      `AuthSession`

      `upgradeAnonymousToEmail({email, password, idempotencyKey?})`
      Upgrades an anonymous user to email/password without losing balances. With email-confirm enabled returns `confirmation_required`.
      `UpgradeAnonymousResult`

      `signOut({forgetAnonymous?})`
      Logout — clears local state first, then best-effort hits the server
      `void`

      `revokeAllSessions()`
      "Sign out everywhere" — invalidates ALL of this user's refresh tokens across every device
      `void`

      `resendConfirmation({email})`
      Resends the confirmation email after signUp with email-confirm. 429 = rate limit (~1/minute)
      `void`

      `refresh()`
      Forces a refresh — usually unnecessary, refresh is lazy
      `AuthSession \| null`

      `getAccessToken()`
      Bearer token for APIs; lazy refresh near expiry
      `string \| null`

      `getCachedSession()` / `getCachedUser()`
      Sync snapshot, no network
      `AuthSession \| AuthUser \| null`

      `getLastLogin()`
      Last login method + email from storage. Useful for UI prefill ("Continue as user@example.com via Google").
      `LastLogin \| null`

      `onAuthChange(cb)`
      Subscription with a discriminated `event`: INITIAL_SESSION (always first), SIGNED_IN/SIGNED_OUT/TOKEN_REFRESHED/USER_UPDATED/PASSWORD_RECOVERY. Callback: `(event, session) => void`
      `unsubscribe`

      `ready()`
      Promise that resolves when the session has hydrated from storage
      `Promise<void>`

      `destroy()` / `isDestroyed()`
      Tears down storage subscriptions and clears listeners. Call on host teardown (SPA route change, hot reload, tests).
      `void` / `boolean`

## Built-in login screen (gate a feature behind sign-in): `paywall.openSignin()`

**You don't need to build your own login UI.** `open()` always shows the price layout, but `PaywallUI` also exposes dedicated handles that open the modal **straight on the built-in auth screen** — email/password + OAuth buttons (per `settings.auth_providers`), fully styled, localized, in Shadow DOM. No custom form, no provider-icon library needed.

```ts

const paywall = new PaywallUI({ paywallId: 'pw_123', auth: true });

// Gate a feature behind sign-in — login only, no plans:
document.getElementById('login').onclick = () => paywall.openSignin();

// New-account flow (starts on the signup form):
document.getElementById('register').onclick = () => paywall.openSignup();
```

Use this whenever sign-in is a **precondition** rather than a purchase prompt:

- A returning customer already bought and just needs to log in so the SDK picks up their subscription.
- You want to require login before unlocking a feature, while keeping `open()` reserved for the Upgrade/plans flow.

| Method | Opens on | Notes |
| --- | --- | --- |
| `openSignin()` | signin form | The explicit name. Use for "log in to gate a feature". |
| `openSignup()` | signup form | Respects `allow_signup` from the paywall layout — if signup is disabled, falls back to signin. |
| `openAuth()` | signin form | Alias of `openSignin()`, kept for backwards compatibility. |

After successful sign-in the modal closes; Back also closes it (the user came only to log in). The trial doesn't block these flows. Without `auth` connected (no managed-auth) they're a no-op — there's no one to sign in. Symmetric to `openSupport()` — a short path to a single task without the full paywall flow.

## Wiring with BillingClient

Pass `auth` to `BillingClient` — the token and identity will be attached automatically, no `getAuthToken` callback needed.

```ts

const auth = new AuthClient({ paywallId: 'pw_123' });
const billing = new BillingClient({ paywallId: 'pw_123', auth });

await billing.bootstrap();    // identity = auth.user; Bearer attached
const user = await billing.getUser();
```

  If you set `identity` explicitly on `BillingClient` — after the first `onAuthChange` event (including `INITIAL_SESSION` on hydration) auto-sync overwrites it with `auth.user`. Don't mix both approaches on the same instance.

---

# SDK 3.0

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3

Bundled paywall SDK for the web, Chrome extensions and Telegram apps — with a headless `/core` export and a REST API for server-side use. Distributed as the npm package `@monetize.software/sdk`, rendered without an iframe inside a Shadow DOM, supports every payment channel (Stripe, Paddle, Chargebee, Freemius, Overpay).

## Pick your integration path

Three scenarios, one SDK. Pick by how much UI you want to own and where your auth lives.

- [Browser — drop-in PaywallUI](/docs-v2/sdk-v3/browser-paywall-ui) — Ready-made paywall modal in Shadow DOM with built-in auth (email / OTP / OAuth). The fastest path — no backend, no UI work. Works in SPAs, Chrome extensions, Telegram Mini Apps.

- [Browser — custom UI](/docs-v2/sdk-v3/browser-custom-ui) — You render your own pricing page and login UI; the SDK provides BillingClient + AuthClient methods plus the API Gateway for metered AI. Full control over every pixel.

- [Headless / server-side](/docs-v2/sdk-v3/headless) — Your own backend, your own auth, your own UI. Use the SDK's /core export from Node / Bun / Edge — or hit the REST API directly from any backend language.

  **Not sure?** Most integrations start with [Browser — drop-in](/docs-v2/sdk-v3/browser-paywall-ui) for fast time-to-paywall, then graduate to one of the other paths if needed. You can switch — the same `paywallId` works across all three.

## Architecture

SDK 3.0 is split into three layers — pull only what you need, the rest stays out of your bundle.

      Module
      Import
      What it does
      Used by

      **Core**
      `@monetize.software/sdk/core`
      API client, `BillingClient`, `AuthClient`, `EventTracker`. No UI, no Preact.
      Custom UI, Headless

      **UI**
      `@monetize.software/sdk/ui`
      `PaywallUI` — paywall rendering in Shadow DOM, ready-made screens.
      Drop-in PaywallUI

      **Full**
      `@monetize.software/sdk`
      Core + UI in one import. Convenient for most integrations.
      Either browser path

## Companion packages

- [@monetize.software/sdk-extension](/docs-v2/sdk-v3/installation#chrome-extension-mv3) — Chrome Extension MV3 — wraps SDK 3.0 in an offscreen document so a single state is shared across popup, content scripts, and the service worker.

- [@monetize.software/sdk-react](/docs-v2/sdk-v3/react) — Provider, hooks (usePaywallUser, usePaywallAccess, usePaywallPrices), and declarative components — works in both browser scenarios.

## What's next

- [Quickstart](/docs-v2/sdk-v3/quickstart) — Zero to paywall in ~10 minutes — code snippets for all three paths

- [Installation](/docs-v2/sdk-v3/installation) — npm install, web vs Chrome extension setup, manifest, host_permissions

---

# React bindings — `@monetize.software/sdk-react`

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/react

Provider, hooks and declarative components on top of `@monetize.software/sdk`. ≤ 2 KB gzip (bindings only — the UI lives inside the SDK).

Works in **both** browser scenarios:

- **[Drop-in PaywallUI](/docs-v2/sdk-v3/browser-paywall-ui)** — use `<PaywallButton>` / `<PaywallGate>` to open the modal declaratively, plus hooks (`usePaywallUser`, `usePaywallTrial`) to read state in your components.
- **[Custom UI](/docs-v2/sdk-v3/browser-custom-ui)** — skip `<PaywallButton>` / `<PaywallGate>`, use hooks only (`usePaywallPrices`, `usePaywallAccess`, `usePaywallUser`) to power your own pricing cards, feature gates, and dashboards.

```bash
pnpm add @monetize.software/sdk-react @monetize.software/sdk react
```

Requires `react: >= 18` (uses `useSyncExternalStore` for concurrent-safe snapshots).

**Working reference app:**
[github.com/monetize-software/sdk-examples/tree/main/nextjs](https://github.com/monetize-software/sdk-examples/tree/main/nextjs)
— Next.js 16 + App Router + Tailwind. Every hook and component shown
below is wired into a runnable page; clone, set two env vars, `npm install`,
`npm run dev`.

## Quick start

```tsx

function App() {
  return (
    <PaywallProvider
      options={{
        paywallId: 'YOUR_ID',
        apiOrigin: 'https://pay.your-domain.com',
        auth: true
      }}
    >
      <PaywallGate fallback={<UpgradeCTA />}>
        <PremiumFeature />
      </PaywallGate>

      <PaywallButton>Upgrade</PaywallButton>
    </PaywallProvider>
  );
}

function UpgradeCTA() {
  const account = usePaywallUser();
  if (account.status === 'loading') return <p>…</p>;
  if (account.status === 'guest') return <p>Hi guest! Unlock full access.</p>;
  return <p>Hi, {account.user?.email ?? 'there'}! Unlock full access.</p>;
}
```

`apiOrigin` must match the `custom_domain` configured for your paywall on the platform.

## `<PaywallProvider>`

Accepts one of two mutually exclusive props (TypeScript discriminated union):

```tsx
<PaywallProvider
  options={{
    paywallId: '3',
    apiOrigin: 'https://pay.your-domain.com',
    auth: true
  }}
>
  <App />
</PaywallProvider>
```

The instance is built inside `useEffect` (client-only); on the server the context value is `null`. Every hook does a graceful fallback (`null` / `{ status: 'loading' }`), so the Provider is safe to render in Next.js without `'use client'` shenanigans on the subtree.

The cleanup effect calls `paywall.destroy()` — StrictMode double-mount won't leak.

```tsx

const paywall = createPaywallUI({ paywallId, apiOrigin });

<PaywallProvider instance={paywall}>
  <App />
</PaywallProvider>
```

Needed for:

- Chrome extensions — `@monetize.software/sdk-extension` ships a structurally compatible `PaywallUI` (with a `RemoteBillingClient` under the hood).
- A shared singleton across several React trees.
- Tests — pass in mocks or a Vitest instance.

In `instance` mode the lifecycle belongs to the host — the Provider does not call `destroy()`.

  **`options` is not reactive.** The Provider creates the instance once; switching `paywallId` between renders won't rebuild `PaywallUI`. Force it via `key`:

  ```tsx
  <PaywallProvider key={paywallId} options={{ paywallId, apiOrigin }}>
  ```

  Reactive option swaps are intentionally not supported — use `key` to force a fresh instance.

## What's available

- [Hooks](/docs-v2/sdk-v3/react/hooks) — usePaywall, usePaywallUser, usePaywallAccess, usePaywallState, usePaywallPrices, usePaywallTrial, usePaywallVisibility, usePaywallEvent

- [Components](/docs-v2/sdk-v3/react/components) — PaywallGate, PaywallButton, PaywallSupportButton

## SSR / Next.js App Router

`@monetize.software/sdk-react` ships a `'use client'` directive on its entrypoint — the bundler crosses the client boundary itself, so the host can import `PaywallProvider` / hooks directly in a server component without wrapping.

```tsx
// app/providers.tsx
'use client';

export function PaywallProviders({ children }) {
  return (
    <PaywallProvider
      options={{
        paywallId: process.env.NEXT_PUBLIC_PAYWALL_ID!,
        apiOrigin: process.env.NEXT_PUBLIC_PAYWALL_ORIGIN!,
        auth: true
      }}
    >
      {children}
    </PaywallProvider>
  );
}

// app/layout.tsx

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <PaywallProviders>{children}</PaywallProviders>
      </body>
    </html>
  );
}
```

Hooks called from server components return the SSR snapshot (`null` / loading). On the client, real data flows in after mount.

## Which SDK channel does it work with?

`@monetize.software/sdk-react` is drop-in for **any** structurally compatible `PaywallUI`:

      Scenario
      Source of `PaywallUI`

      Web / SPA
      Provider `options` → internally `new PaywallUI()` from `@monetize.software/sdk`.

      Chrome Extension (React popup)
      `createPaywallUI()` from `@monetize.software/sdk-extension` (Remote-proxied) → Provider `instance`.

      Tests (vitest + RTL)
      Mocks or a real `PaywallUI` → Provider `instance`.

## Re-exported types

For ergonomics, core SDK types are re-exported — the host doesn't need a second import from `@monetize.software/sdk`:

```ts

```

`PaywallUserState` (the discriminated union returned by `usePaywallUser()`) is exported directly from `@monetize.software/sdk-react`:

```ts

```

Single source of truth is still `@monetize.software/sdk` — this is pure pass-through.

## Next steps

- [Hooks](/docs-v2/sdk-v3/react/hooks) — Hook-by-hook walkthrough: re-render rules, SSR behaviour.

- [Components](/docs-v2/sdk-v3/react/components) — PaywallGate / PaywallButton / PaywallSupportButton — patterns and render props.

- [Quickstart — SaaS Web](/docs-v2/guide/sdk-v3-web) — End-to-end integration into a React SaaS.

- [Next.js example](https://github.com/monetize-software/sdk-examples/tree/main/nextjs) — Runnable Next.js 16 + App Router app exercising every public hook and component.

---

# API Gateway

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/api-gateway

`ApiGatewayClient` is the SDK 3.0 client for metered AI calls **from the browser**: SPA, Chrome extension, Telegram Mini App. The proxy forwards the request to OpenAI/Anthropic/any configured HTTP API using server-held keys, debits one credit from the user's balance for the provider's `query_type`, and returns the response as-is (including `text/event-stream`).

The point of routing through us is that **your provider API keys never leave our server**. In a browser-only app you can't ship `OPENAI_API_KEY` to the client; the gateway is what makes metered AI possible without a backend of your own.

  **When to use.** Only when your paywall has `tokenization` enabled and at least one [API Provider](/docs-v2/api-provider/overview) configured. Without them `/balances` returns an empty array and `gateway.call()` fails with `provider-disabled`.

  **Headless / your own backend?** Don't use `ApiGatewayClient` server-side — your backend already has the provider keys and can call OpenAI/Anthropic directly with lower latency. Debit credits after success via [`billing.debitTokens()`](/docs-v2/sdk-v3/headless-server#token-credit-and-debit) (`apiKey` + identity). The gateway exists for browser scenarios; routing through it from your own server adds a network hop for no benefit.

## Quick start

```ts

const auth = new AuthClient({ paywallId: 'pw_123' });
const billing = new BillingClient({ paywallId: 'pw_123', auth });

// The factory automatically wires Bearer and balance state from this billing.
const gateway = billing.createApiGatewayClient();

billing.onBalanceChange((balances) => {
  console.log('Quota:', balances); // [{ type: 'standard', count: 42 }, ...]
});

try {
  const res = await gateway.call({
    providerId: 'prov_openai_chat',
    path: 'v1/chat/completions',
    body: {
      model: 'gpt-4',
      messages: [{ role: 'user', content: 'Hello' }]
    }
  });
  const data = await res.json();
} catch (e) {
  if (e instanceof QuotaExceededError) {
    paywall.open(); // user is out of quota — show upgrade
  } else throw e;
}
```

## In a Chrome extension

In an MV3 extension you use `@monetize.software/sdk-extension`, where `BillingClient`/`AuthClient` are proxied to the offscreen document. The gateway factory `billing.createApiGatewayClient()` is **not** available there — `paywall.billing` is a remote proxy and does not mirror it. Instead, **construct `ApiGatewayClient` yourself** from `@monetize.software/sdk/core` and pass the extension's auth as the source: the Bearer is still resolved once in offscreen via `getAccessToken()`, so there is a single AuthClient and no token duplication.

```ts

// Import BOTH symbols from the same core entry — see the warning below.

const paywall = new PaywallUI({ paywallId: 'pw_123', apiOrigin, auth: true });

const gateway = new ApiGatewayClient({
  paywallId: 'pw_123',
  apiOrigin,                                    // same custom_domain as PaywallUI
  auth: paywall.auth as unknown as AuthClient,  // RemoteAuthClient, duck-typed; Bearer comes from offscreen
  onChargeSuccess: () => {
    // The extension billing lives in offscreen — force a refetch so the UI counter updates.
    void paywall.billing.getBalances({ force: true }).catch(() => {});
  },
  onQuotaExceeded: () => paywall.open()         // 402 → show the paywall
});

try {
  const res = await gateway.call({ providerId: 'prov_openai_chat', path: 'v1/chat/completions', body });
} catch (e) {
  if (e instanceof QuotaExceededError) paywall.open();
}
```

  **Import `ApiGatewayClient` _and_ `QuotaExceededError` from the same `@monetize.software/sdk/core` entry.** The extension content bundle inlines its own copy of `sdk`. If you construct the gateway from one copy and check `instanceof QuotaExceededError` against another (e.g. a symbol re-exported from `sdk-extension`), the class identities differ and `instanceof` silently returns `false`. Constructing the gateway from `@monetize.software/sdk/core` keeps it aligned with the error you catch. This is also why `sdk-extension` deliberately does **not** re-export these symbols.

## Principles

- **Raw `Response`.** `gateway.call()` returns a plain `fetch` Response, not a wrapper. The caller decides: `.json()`, `.text()`, `.body.getReader()`, async-iter — everything works out of the box. The SDK doesn't ship its own SSE parser — parse raw chunks yourself or use your existing streaming library.
- **Authorization from `AuthClient`.** If billing was created with `auth`, the gateway automatically sends `Authorization: Bearer <access_token>`; lazy refresh works just like for every other SDK request.
- **Optimistic balance decrement.** On success, `decrementBalanceLocal()` reduces `cachedBalances` for the matching `query_type` immediately; listeners get the update instantly. On a 402 the SDK auto-fires `refreshBalances()` so the UI gets a fresh snapshot.
- **402 → `QuotaExceededError`.** The backend returns 402 with `details.balances`, `details.queryType`, `details.currentBalance` — the SDK parses and throws a typed error. PaywallUI catches it automatically and opens the upgrade modal; a headless caller handles it itself.

## Streaming (SSE)

The backend proxy passes `text/event-stream` responses through unchanged, with the same chunks the provider sent.

```ts
const res = await gateway.call({
  providerId: 'prov_openai_chat',
  path: 'v1/chat/completions',
  body: {
    model: 'gpt-4',
    stream: true,
    messages: [{ role: 'user', content: 'Tell me a story' }]
  },
  signal: controller.signal
});

const reader = res.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value, { stream: true });
  // chunk is raw SSE: "data: {...}\n\n"; parse as usual
}
```

`signal: AbortSignal` is supported — `controller.abort()` cancels upstream, the backend cancels the provider request and logs the stream as `aborted`.

## Balances

`BillingClient` keeps balances in memory with a 5-second TTL plus a listener. You can read them manually:

```ts
const balances = await billing.getBalances();
// [{ type: 'free', count: 100 }, { type: 'standard', count: 9 }]

const sync = billing.getCachedBalances(); // null if never loaded

const off = billing.onBalanceChange((balances) => {
  /* re-render counter */
});
off(); // unsubscribe

await billing.refreshBalances(); // force re-fetch
```

After every successful `gateway.call()` balances are decremented locally, without a second round-trip to the server. The only authoritative source is the server-side balance; the local cache is a UX facade.

## `gateway.call()` options

      Field
      Type
      What it does

      `providerId`
      `string`
      API provider UUID from the dashboard ([API Providers](/docs-v2/api-provider/overview) section)

      `path`
      `string?`
      Path after the provider (`v1/chat/completions`, `messages`, ...). Concatenated via `/`

      `method`
      `'GET' \| 'POST'`
      Defaults to `POST`

      `body`
      `unknown \| FormData \| Blob \| ReadableStream \| string`
      Object → JSON.stringify + `Content-Type: application/json`. FormData/Blob — the browser sets the boundary. ReadableStream/string — passed through

      `headers`
      `Record<string,string>`
      Extra headers. Doesn't overwrite `Authorization` or `X-Paywall-Id`

      `signal`
      `AbortSignal`
      Cancel the request (important for long streams)

## `QuotaExceededError`

```ts
class QuotaExceededError extends PaywallError {
  code: 'not_enough_queries';
  status: 402;
  balances: Balance[];          // every balance the user has at the moment of 402
  queryType: string;             // which query_type ran out
  currentBalance: Balance | null; // entry for queryType, usually { type, count: 0 }
}
```

Standard host-app handler:

```ts

try {
  const res = await gateway.call({ providerId, body });
  /* ... */
} catch (e) {
  if (e instanceof QuotaExceededError) {
    // Balances have already been refreshed via refreshBalances() — onBalanceChange
    // emitted a new snapshot already. Open the paywall.
    paywall.open();
    return;
  }
  throw e;
}
```

## What's under the hood

## Related pages

- [API Provider Overview](/docs-v2/api-provider/overview) — How to configure an API provider on the platform

- [Authentication](/docs-v2/sdk-v3/auth) — AuthClient — Bearer tokens for gateway calls

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — Bootstrap, identity and balance state for the UI

- [Headless / server-side](/docs-v2/sdk-v3/headless-server#token-credit-and-debit) — From your own backend — call providers directly and credit/debit balances via creditTokens/debitTokens

---

# Anonymous sign-in

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth/anonymous

`AuthClient.signInAnonymously()` creates a user without an email — for trial access without a sign-up form. The backend issues a regular `AuthSession`, and `BillingClient` treats it the same as an email user. Concept and dashboard toggle are described in [Paywall → Anonymous sign-in](/docs-v2/paywall/anonymous-sign-in); the v2 equivalent is in [SDK v2 → Anonymous sign-in](/docs-v2/sdk-v2/client-side/anonymous-sign-in).

  Available only when `allow_anonymous` is enabled in paywall settings. Otherwise the method fails with `PaywallError(code='anonymous_disabled')`.

## Signature

```ts
auth.signInAnonymously(input?: {
  userMeta?: Record<string, string>;
  /**
   * Force a brand-new anonymous user — skips the "resume previous anon"
   * shortcut. See "Forcing a new anonymous user" below.
   */
  forceNewAnon?: boolean;
}): Promise<AuthSession>;
```

Returns an `AuthSession`. `user.is_anonymous === true`, `user.email === null`.

## Basic flow

```ts

const auth = new AuthClient({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  storage: yourStorageAdapter
});

const session = await auth.signInAnonymously();
console.log(session.user.id, session.user.is_anonymous); // "usr_abc...", true
```

The same `auth` can then be passed to `BillingClient` — the anonymous user receives a balances list and can spend trial tokens through `ApiGatewayClient` exactly like a signed-in user.

## Default behaviour: resume

The method is **idempotent** and **preserves the same user.id** across sessions:

1. If already signed in anonymously (`session.user.is_anonymous === true`) → no-op, return the current session. The UI can call this in a render loop with no consequences.
2. If `anonRefreshToken` from a previous anon-signin is still in storage → call `/auth/refresh` with it. The user comes back to **the same account** with the same balances.
3. Otherwise → create a new anon user.

This means: if a user signed in anonymously, spent part of their trial balance, signed out (via `signOut()` without `forgetAnonymous`), the next `signInAnonymously()` returns the same account with the remaining balance. Don't reimplement this in your app — the SDK already handles it.

  Parallel `signInAnonymously()` calls collapse into one request. Two clicks on "Continue as guest" create **one** anonymous user, not two — but if your button already has a debounce, keep it: cheaper than relying on the dedupe alone.

## Forcing a new anonymous user

By default the SDK is sticky: subsequent `signInAnonymously()` calls return the same anon user (steps 1–2 above). To bypass that and always mint a fresh anon user, pass `forceNewAnon: true`.

```ts
// Switch account: drop the current one, create a fresh anon user
await auth.signOut({ forgetAnonymous: true });
const fresh = await auth.signInAnonymously({ forceNewAnon: true });
```

Used in "Switch account" UIs — when the user wants to start over.

## Upgrade to an email user

An anonymous user can "complete" their account with an email and password. Balances and trial quotas are **preserved** — `user.id` doesn't change.

```ts
const result = await auth.upgradeAnonymousToEmail({
  email: 'user@example.com',
  password: 'secret123',
  idempotencyKey: crypto.randomUUID() // double-click protection
});

if (result.kind === 'updated') {
  // Platform email-confirm OFF: session updated immediately,
  // user.email filled, is_anonymous=false
} else {
  // result.kind === 'confirmation_required'
  // Platform email-confirm ON: wait for the user to click the email link.
  // The current session STAYS anonymous until confirmation,
  // password is applied immediately — they can sign in with it later.
}
```

  Pass `idempotencyKey` — the upgrade endpoint isn't idempotent on the backend, and a double-submit can send two confirmation emails. The SDK does not dedupe upgrade calls.

## Logout: forget or resume?

```ts
// 1) Soft signOut — the anon refresh token stays in storage,
//    the next signInAnonymously() resumes the SAME account.
await auth.signOut();

// 2) Hard signOut — the anon token is forgotten, the next signin
//    creates a NEW user with empty balances.
await auth.signOut({ forgetAnonymous: true });
```

Scenarios:
- User closed the tab and came back tomorrow — soft signOut auto-restores the trial balance on reopen.
- User explicitly clicks "Reset account" — hard signOut.
- You're testing the trial flow on your machine — hard signOut.

## Reacting in UI

```ts
const unsubscribe = auth.onAuthChange((event, session) => {
  // `USER_UPDATED` arrives after upgradeAnonymousToEmail (same user.id,
  // but is_anonymous=false and email filled) — no need to handle separately,
  // the conditions below switch UI from banner to profile.
  if (!session) {
    showLoggedOut();
    return;
  }
  if (session.user.is_anonymous) {
    showAnonymousBanner(); // "Save your account?" CTA
  } else {
    showProfile(session.user.email);
  }
});
```

`is_anonymous` is the main signal for UI: "should I prompt to upgrade?". After `upgradeAnonymousToEmail()` (`kind: 'updated'`) the flag flips to `false` locally; for `confirmation_required` — after user confirmation and the next `/auth/refresh`.

## See also

- [Concept and dashboard toggle](/docs-v2/paywall/anonymous-sign-in)

- [Session management](/docs-v2/sdk-v3/auth/session)

- [Email & password upgrade](/docs-v2/sdk-v3/auth/email-password)

- [SDK v2 equivalent](/docs-v2/sdk-v2/client-side/anonymous-sign-in)

---

# Email & password

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth/email-password

Classic email and password sign-in — `signInWithEmail` and `signUp`. Behaviour depends on the platform's email-confirmation setting: when it's on, new users get an email with a code and must enter it; when it's off, `signUp` returns a session immediately.

## signInWithEmail

```ts
const session = await auth.signInWithEmail({
  email: 'user@example.com',
  password: 'secret123'
});
```

On success:

- the session is written to storage (key `pw-<paywallId>-auth-v1`
- `onAuthChange` is emitted with the new session,
- a `BillingClient` bound to this `auth` starts attaching the Bearer token.

### Parameters

    ```ts
    auth.signInWithEmail(input: {
      email: string;
      password: string;
      userMeta?: Record<string, string>;
    }): Promise<AuthSession>
    ```

    ```ts
    interface AuthSession {
      access_token: string;
      refresh_token: string;
      /** Absolute timestamp in ms (Date.now()-comparable). */
      expires_at: number;
      user: {
        id: string;
        email: string;
        country?: string | null;
      };
    }
    ```

    ```ts
    // userMeta is stored against the user's record on this paywall —
    // useful for arbitrary fields like traffic source, campaign, A/B variant.
    await auth.signInWithEmail({
      email: 'user@example.com',
      password: 'secret123',
      userMeta: {
        source: 'extension_popup',
        campaign: 'spring_sale_2026'
      }
    });
    ```

### Errors

    Wrong email or password — `PaywallError` with `status: 401` and `code: 'invalid_credentials'` (when the backend passes it through).

    ```ts
    try {
      await auth.signInWithEmail({ email, password });
    } catch (e) {
      if (e instanceof PaywallError && e.status === 401) {
        showError('Wrong email or password');
        return;
      }
      throw e;
    }
    ```

    Browser couldn't reach the API — `PaywallError` with `code: 'network_error'`. The SDK does not auto-retry: decide on the UI side (show "try again later" or a retry button).

    the platform's auth backend returned 5xx — `PaywallError` with `status: 502` and `code: 'upstream'`. Rare, also no auto-retry.

## signUp

```ts
const result = await auth.signUp({
  email: 'new@example.com',
  password: 'secret123'
});

if (result.kind === 'signed_in') {
  // session issued already, user is signed in
  console.log(result.session.user.email);
} else {
  // result.kind === 'confirmation_required' — email confirmation needed
  // show an "enter the code from the email" screen and call verifyOtp
}
```

### Discriminated union

```ts
type SignUpResult =
  | { kind: 'signed_in'; session: AuthSession }
  | { kind: 'confirmation_required'; user: { id: string; email: string } };
```

  **Confirmation required.** When the platform has email confirmation enabled, `signUp` does NOT issue tokens — it returns `kind: 'confirmation_required'`. The user gets an email with a 6-digit code; the next step is `verifyOtp({ type: 'signup', token: '<code>' })`. Details: [Email OTP](/docs-v2/sdk-v3/auth/otp).

### Full signup flow with email confirmation

### Step 1: call signUp

```ts
const res = await auth.signUp({ email, password });

if (res.kind === 'signed_in') {
  redirectToApp();
  return;
}
// res.kind === 'confirmation_required'
showVerifyCodeScreen({ email });
```

### Step 2: user enters the code

```ts
const session = await auth.verifyOtp({
  email,
  token: codeFromInput,
  type: 'signup'
});
// session is signed in — auth.getCachedUser() returns the user
```

### Step 3: business as usual

`onAuthChange` fires — `BillingClient` picks up the token and identity automatically.

## Handling signin/signup on a single UI

You often want one "email + password" screen without forcing the user to pick "I don't have an account yet" / "I have an account". A handy pattern — `signUp` first, fall back to `signInWithEmail` on `user_already_exists`:

```ts
async function loginOrSignUp(email: string, password: string) {
  try {
    const res = await auth.signUp({ email, password });
    return res; // signed_in or confirmation_required
  } catch (e) {
    // the platform's auth backend returns user_already_exists (status 400/422)
    const isAlreadyExists =
      e instanceof PaywallError &&
      (e.code === 'user_already_exists' || e.code === 'email_exists');

    if (!isAlreadyExists) throw e;

    const session = await auth.signInWithEmail({ email, password });
    return { kind: 'signed_in' as const, session };
  }
}
```

  An alternative — use [Email OTP](/docs-v2/sdk-v3/auth/otp): one path for both signin and signup, no password. More convenient in a Chrome extension where password managers often misbehave.

## Security

- **Don't log `password` to Sentry/console.** The SDK never writes it anywhere — but if you wrap it in your own code, double-check that only email is in traces.
- **Minimum length** — `signUp` does not validate on the client; the platform's auth backend rejects short passwords with `weak_password`. For stricter rules, validate in your UI before calling the SDK.
- **Rate limit.** the platform's auth backend rate-limits signin/signup by IP — after 3–4 failed attempts it starts returning 429. The SDK does not auto-retry; in the UI show "try later" without permanently disabling the button.

## Next steps

- [Session management](/docs-v2/sdk-v3/auth/session) — `onAuthChange`, `signOut`, using `AuthSession` in API calls.
- [Email OTP](/docs-v2/sdk-v3/auth/otp) — passwordless sign-in with one email.
- [Password reset](/docs-v2/sdk-v3/auth/password-reset) — "forgot password" flow.

---

# OAuth (Google, Apple)

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth/oauth

One-click sign-in via Google or Apple. Under the hood — a PKCE flow through a popup: the SDK generates a code verifier, opens the popup at the provider's authorize URL through the platform, exchanges the one-time code for an `AuthSession` after the popup returns.

```ts
const session = await auth.signInWithOAuth({ provider: 'google' });
```

The method is async: resolves after the full cycle (popup opened → user signed in at the provider → callback page posted the code → backend exchanged it for a session).

## signInWithOAuth

    ```ts
    auth.signInWithOAuth(input: {
      provider: 'google' | 'apple' | 'github' | 'facebook';
      scopes?: string;
      userMeta?: Record<string, string>;
    }): Promise<AuthSession>
    ```

          Field
          Default
          What it does

          `provider`
          —
          `'google'` or `'apple'`. The type also accepts `'github'` / `'facebook'` for future use but those aren't live on the platform yet.

          `scopes`
          —
          Extra provider scopes (space-separated). For Google, `openid email profile` is implied — add only if you need API access (e.g. `https://www.googleapis.com/auth/calendar.readonly`).

          `userMeta`
          —
          Custom metadata to store against the user on this paywall — same as in `signInWithEmail`.

    `Promise<AuthSession>` — resolves only on full success. Popup close, provider rejection, timeout — every case throws a `PaywallError` (see below).

  **Call from a user gesture only.** `window.open` is blocked by browsers when called outside a click/tap handler. If you fire OAuth automatically (e.g. on first app load) the popup is always blocked and the method throws `popup_blocked`.

## Setup — none required

Google and Apple are available on every paywall by default. The OAuth applications, redirect URIs, and platform credentials are wired up by monetize.software — you don't manage them and there is no toggle to flip.

You can call `signInWithOAuth({ provider: 'google' })` or `signInWithOAuth({ provider: 'apple' })` immediately after `new AuthClient(...)` / `new PaywallUI({ auth: true })`.

  **No CORS / Allowed Origins config needed.** SDK 3.0 uses Bearer auth (not cookies) and our API has open CORS by design. The host of your site or extension doesn't need to be whitelisted anywhere.

  **`OAuthProvider` type includes `'github'` and `'facebook'`** — these are reserved for future support. Right now only `'google'` and `'apple'` are wired up on the platform; calls with the other two will fail.

## How the flow works

The SDK opens a popup at the provider via our auth backend, the callback page `postMessage`s the authorization code back to the SDK, and the SDK exchanges it for a session — all PKCE-protected.

For your app, this is one `await auth.signInWithOAuth({ provider })` call. When it resolves, the session is already persisted and `onAuthChange` has fired. See [Security](#security) below for the threat model.

## Platform notes

### Web / SPA

Plain `window.open` works out of the box. No configuration needed.

### Chrome Extension (MV3)

The basic flow works too: the SDK calls `window.open` from a content script or a built-in extension page, the popup opens on our domain, postMessage returns to the opener.

**Gotcha: some providers (Apple especially) check `referer` and may refuse** if the popup opens without a top-level context. The fix is a custom `openPopup`:

```ts
const auth = new AuthClient({
  paywallId: 'pw_123',
  openPopup: (url, name) => {
    // option 1 — chrome.windows.create (opens a standalone browser window)
    chrome.windows.create({ url, type: 'popup', width: 480, height: 640 });
    // returning a Window-like object is harder — chrome.windows requires polling
    // via chrome.windows.onRemoved → forward to the SDK through events.
    // If you don't need it — option 2.

    // option 2 — regular window.open stays
    return window.open(url, name, 'width=480,height=640,popup=yes');
  }
});
```

  **`chrome.identity.launchWebAuthFlow` is not supported.** It uses a per-extension redirect URL (`https://<extension-id>.chromiumapp.org/...`) that isn't pre-registered with OAuth providers. Use a normal popup against the SDK's default callback instead.

### Telegram Mini App

There's no full `window.open` inside a Telegram WebView — the embedded browser opens links in the system browser. OAuth works there via `window.Telegram.WebApp.openLink()` switching to a browser, but the callback has to come back to the Mini App via a deep link. That's non-standard — `signInWithOAuth` doesn't fit directly; you'd need a custom wrapper. If you need this, contact support.

## Errors

      `code`
      When
      What to show

      `popup_blocked`
      Browser blocked the popup (call outside a user gesture).
      "Sign in with Google" button with an explicit re-click.

      `oauth_cancelled`
      User closed the popup before completion.
      Silently return to the login screen.

      `oauth_failed`
      Provider returned an error (e.g. user denied access).
      "Couldn't sign in, try another method".

      `oauth_timeout`
      5 minutes without a code from the popup (user abandoned without closing).
      Silently cancel and offer to start over.

      `oauth_unavailable`
      SDK called from Node.js or another runtime without `window`.
      Developer bug.

      `exchange_failed` / 401
      the platform's auth backend rejected the code (stolen-from-logs code, state typo).
      "Session expired, please try again".

## Full example

```tsx
function GoogleSignInButton() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleClick = async () => {
    setLoading(true);
    setError(null);
    try {
      await auth.signInWithOAuth({ provider: 'google' });
      // ✅ session is already in AuthClient, onAuthChange fired, BillingClient picked it up
    } catch (e) {
      if (!(e instanceof PaywallError)) throw e;
      switch (e.code) {
        case 'oauth_cancelled':
          // user changed their mind — say nothing
          break;
        case 'popup_blocked':
          setError('The browser blocked the window. Click again.');
          break;
        default:
          setError("Couldn't sign in. Try another method.");
      }
    } finally {
      setLoading(false);
    }
  };

  return (
    <>
      <button onClick={handleClick} disabled={loading}>
        {loading ? 'Opening window…' : 'Sign in with Google'}
      </button>
      {error && <div className="error">{error}</div>}
    </>
  );
}
```

## Low-level: `startOAuthFlow` / `completeOAuthFlow`

Split the OAuth handshake when you need to run the popup and the code exchange in different processes — for example, the `@monetize.software/sdk-extension` offscreen architecture, where the popup lives in a content script but the exchange must happen in the offscreen document.

```ts
const { authorize_url, state } = await auth.startOAuthFlow({ provider: 'google' });
// open the popup yourself, capture the code via your own transport
const session = await auth.completeOAuthFlow({ state, code });
```

In a normal browser context, prefer `signInWithOAuth` — it handles popup + exchange in one call.

## Security

- **Code verifier** — a secret for the duration of the OAuth flow. The SDK keeps it in the method's closure (not in storage); it won't survive a page reload. If the user hard-reloads mid-OAuth, the code arrives at an opener that's gone and there's nothing to resolve. This is by design: the verifier ↔ code pair must be atomic.
- **State** — the nonce that defends against postMessage spoofing. The SDK never reuses one.
- **Redirect URI** — a fixed monetize.software callback (`/paywall/v3/auth/callback`). You don't configure it, and there's no per-customer redirect surface to misconfigure.

## Next steps

- [Session management](/docs-v2/sdk-v3/auth/session) — what to do after success.
- [Error codes](/docs-v2/sdk-v3/errors) — full list of `PaywallError.code`.

---

# Email OTP

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth/otp

Passwordless sign-in: the user enters an email, receives a 6-digit code, types it in — `AuthSession` is ready. The same flow covers signin and signup: if the user doesn't exist yet they're created automatically.

```ts
await auth.sendOtp({ email: 'user@example.com' });
// ... show the code input UI
const session = await auth.verifyOtp({
  email: 'user@example.com',
  token: '123456'
});
```

  **When to pick OTP over password.** In Chrome extensions, password managers often misbehave (autofill breaks because of isolation). OTP minimises friction: one email and the user is in. Downside — every sign-in requires opening the inbox; on the web, where password managers work well, a classic password may be more convenient.

## sendOtp

Sends a code to the email. The backend always returns `ok` (anti-enumeration: you can't tell from the response whether the user exists). A real error ("invalid email") surfaces only on the next step — `verifyOtp`.

    ```ts
    auth.sendOtp(input: {
      email: string;
      createUser?: boolean;
      userMeta?: Record<string, unknown>;
    }): Promise<void>
    ```

          Field
          Default
          What it does

          `email`
          —
          User's email. No format validation on the client — the platform's auth backend handles it.

          `createUser`
          `true`
          If `false` and the user doesn't exist — the code isn't sent (but the response is still `ok`). Use `false` for "sign-in only" flows.

        `userMeta`
        —
        Stored as user metadata on the new account; ignored for existing users.

    `Promise<void>` — success means "the backend accepted the request", not "the email was delivered". Mirrors the anti-enumeration logic on the SDK side.

### sendOtp errors

      Situation
      `code` / `status`
      What to show the user

      Email doesn't look like an email
      `invalid_email` / 400
      "Check your email"

      Too many sends (rate limit)
      `over_email_send_rate_limit` / 429
      "Try again in a minute"

      Network is down
      `network_error`
      "Send again" button

## verifyOtp

Verifies the code, sets the session on success and emits `onAuthChange`. Event-wise: `SIGNED_IN` for `type='email'|'signup'|'magiclink'|'invite'`; `PASSWORD_RECOVERY` for `type='recovery'` — so listeners can tell "user signed in" from "user opened the reset link, show the new-password form".

```ts
auth.verifyOtp(input: {
  email: string;
  token: string;
  type?: 'email' | 'recovery' | 'signup' | 'magiclink' | 'invite';
  userMeta?: Record<string, string>;
}): Promise<AuthSession>
```

### The `type` parameter

      `type`
      When to use

      `'email'` (default)
      Standard OTP flow: signin/signup via `sendOtp`.

      `'recovery'`
      After [`requestPasswordReset`](/docs-v2/sdk-v3/auth/password-reset) — yields a recovery session so you can call `updatePassword`.

      `'signup'`
      After `signUp` with email confirmation enabled on the platform. Use when you want to flag "registration confirmation" separately.

      `'magiclink'`
      If you send a magic link instead of an OTP code — extract the token from the link URL.

      `'invite'`
      Accepting an invite — rarely used, kept for compatibility.

### verifyOtp errors

      Situation
      `code` / `status`

      Wrong code, expired code, or email without an OTP sent
      `invalid_otp` / 401

      Nonexistent `type` (typo)
      `invalid_type` / 400

  **OTP TTL.** 1 hour by default (configured platform-side). If your UI mentions the code lifetime ("code valid for X minutes"), use a generic phrasing rather than hard-coding the value.

## Full flow

### Step 1: request a code

```ts
await auth.sendOtp({ email });
showCodeInputScreen({ email });
```

### Step 2: show the code input

The UI should:
- store the email from step 1 (the user shouldn't have to re-enter it),
- offer a "Resend" button with a 30-60 second delay (anti-spam),
- auto-focus the input.

### Step 3: verify the code

```ts
try {
  const session = await auth.verifyOtp({ email, token: code });
  // ✅ user signed in
  onLoggedIn(session);
} catch (e) {
  if (e instanceof PaywallError && e.code === 'invalid_otp') {
    showError('Wrong or expired code');
    return;
  }
  throw e;
}
```

### Step 4: business as usual

`AuthClient` now holds the session and emits `onAuthChange`; `BillingClient` picks up the token.

## Resend timer: example

```tsx
function OtpScreen({ email, onLoggedIn }) {
  const [code, setCode] = useState('');
  const [resendIn, setResendIn] = useState(45);

  useEffect(() => {
    if (resendIn === 0) return;
    const t = setTimeout(() => setResendIn((s) => s - 1), 1000);
    return () => clearTimeout(t);
  }, [resendIn]);

  const submit = async () => {
    try {
      const session = await auth.verifyOtp({ email, token: code });
      onLoggedIn(session);
    } catch (e) {
      // show error
    }
  };

  const resend = async () => {
    await auth.sendOtp({ email });
    setResendIn(45);
  };

  return (
    <div>
      <input value={code} onChange={(e) => setCode(e.target.value)} />
      <button onClick={submit}>Verify</button>
      <button onClick={resend} disabled={resendIn > 0}>
        {resendIn > 0 ? `Resend in ${resendIn}s` : 'Resend'}
      </button>
    </div>
  );
}
```

## Anti-enumeration: things to watch for

The backend always returns `ok` for `sendOtp` — even when the user doesn't exist. This is by design: you can't tell from the response whether the email is registered. Consequence for UI:

- **Don't show "no such user"** between `sendOtp` and `verifyOtp` — you don't have that info until the code is entered.
- **Error messages should be neutral.** "Wrong code" works both for "no code because user doesn't exist" and for "code expired / mistyped".

## Next steps

- [Password reset](/docs-v2/sdk-v3/auth/password-reset) — reuses `verifyOtp` with `type: 'recovery'`.
- [Session management](/docs-v2/sdk-v3/auth/session) — what to do after a successful `verifyOtp`.

---

# Password reset

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth/password-reset

Password recovery is three steps: request a recovery email, enter the code from the email, change the password. Under the hood, [`verifyOtp`](/docs-v2/sdk-v3/auth/otp) (with `type: 'recovery'`) and `updatePassword` are reused, so there's no separate "recovery mode" in `AuthClient` — after `verifyOtp` the user is in a regular signed-in session, just with an access token from a recovery grant.

```ts
await auth.requestPasswordReset({ email });

// user enters the code from the email:
await auth.verifyOtp({ email, token: code, type: 'recovery' });

// now we have a valid session — change the password:
await auth.updatePassword({ password: newPassword });
```

## requestPasswordReset

Triggers a recovery email. Like `sendOtp`, always returns `ok` (anti-enumeration).

    ```ts
    auth.requestPasswordReset(input: {
      email: string;
    }): Promise<void>
    ```

    `Promise<void>` — success means "the backend accepted the request". Successful delivery is not guaranteed (bounce, spam filter).

    The only externally visible error is `over_email_send_rate_limit` (status 429): too many reset requests from the same user.

  **What's in the email — a code or a link?** The SDK expects a 6-digit code. The platform's default email template sends a code; if a link arrives instead (legacy templates), extract `token=...` from it in your UI before calling `verifyOtp`.

## updatePassword

Changes the password of the current signed-in session. Works after `verifyOtp({ type: 'recovery' })` (a recovery session) and from a regular signed-in session (the "change password in settings" feature).

```ts
auth.updatePassword(input: { password: string }): Promise<void>
```

### When there's no session

The method throws `PaywallError('not_authenticated')` before the network request. That means:

- the user didn't pass `verifyOtp` (or did, but `AuthClient` hadn't stored the session — no such races exist, the method awaits);
- the session expired and the refresh token is invalid.

In real UI this is a rare path: there are seconds between "enter code" and "enter new password".

### When the password is weak

The platform's auth backend validates length (minimum 6) and applies any additional policy rules. A weak password yields `PaywallError` with `code: 'weak_password'`, `status: 400`.

```ts
try {
  await auth.updatePassword({ password: newPassword });
} catch (e) {
  if (e instanceof PaywallError && e.code === 'weak_password') {
    showError('Password is too weak');
    return;
  }
  throw e;
}
```

  **After `updatePassword` the session is NOT recreated.** The access token stays the one issued after `verifyOtp`/regular signin. This is deliberate: there's no need to sign out a user who just changed their password. If you want "sign out from all devices after a password change" — that's a separate feature on the backend; the SDK doesn't ship it.

## Full "Forgot password" flow

### Step 1: "Forgot password?" → request email

UI asks for the email and calls `requestPasswordReset`:

```ts
await auth.requestPasswordReset({ email });
showStep('enter-recovery-code');
```

### Step 2: enter the code

```ts
try {
  await auth.verifyOtp({ email, token: code, type: 'recovery' });
  showStep('enter-new-password');
} catch (e) {
  if (e instanceof PaywallError && e.code === 'invalid_otp') {
    showError('Wrong or expired code');
    return;
  }
  throw e;
}
```

### Step 3: enter the new password

```ts
try {
  await auth.updatePassword({ password: newPassword });
  showStep('done');
} catch (e) {
  if (e instanceof PaywallError && e.code === 'weak_password') {
    showError('Password is too weak — add more characters');
    return;
  }
  throw e;
}
```

### Step 4: done

After `updatePassword` the user is already signed in (`AuthClient.getCachedUser()` returns them) — redirect straight into the app, no need to force a re-login.

## Alt-flow: "change password in settings"

If the user is already signed in and just wants to change their password — only `updatePassword` is needed. No recovery email.

```ts
// on the "Settings → Security" screen:
async function changePassword(currentPassword: string, newPassword: string) {
  // (optional) re-verify the current password via signInWithEmail
  const email = auth.getCachedUser()?.email;
  if (!email) throw new Error('not authenticated');

  await auth.signInWithEmail({ email, password: currentPassword });
  // if signIn fails — current password is wrong; surface the error
  await auth.updatePassword({ password: newPassword });
}
```

  Re-verifying via `signInWithEmail` is needed because `updatePassword` itself doesn't require the current password — the access token is enough. Re-auth protects against "user left a laptop unlocked, someone changed the password".

## Security

- **Anti-enumeration in UI.** Show neutral messages on every step. After `requestPasswordReset` — "If that email exists, we sent a message", not "Email sent" (the latter reveals registration).
- **Recovery token is short-lived.** The recovery session has the same lifetime as a regular access token (1 hour by default). If the user leaves the "enter new password" screen for half an hour — `updatePassword` still works; for an hour and a half — they have to start over.
- **Hold the email in state between steps.** Don't make the user type it again — that's friction and a typo opportunity.

## Next steps

- [Email OTP](/docs-v2/sdk-v3/auth/otp) — `verifyOtp` and the general code mechanics.
- [Session management](/docs-v2/sdk-v3/auth/session) — `signOut`, `onAuthChange`, what the user sees after a password change.

---

# Session management

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/auth/session

After a successful sign-in (by any method — email, OTP, OAuth, anonymous), `AuthClient` stores `AuthSession` locally and refreshes the access token on a timer. This page covers how to read state, react to changes, sign out, and integrate the session into code outside `BillingClient`.

## AuthSession

```ts
interface AuthSession {
  access_token: string;
  refresh_token: string;
  /** Absolute timestamp in ms (Date.now()-comparable). */
  expires_at: number;
  user: {
    id: string;
    /** null for anonymous users (signInAnonymously). */
    email: string | null;
    country?: string | null;
    is_anonymous?: boolean;
  };
}
```

Default access token lifetime is 1 hour, refresh token — 30 days of inactivity (configured platform-side). The SDK abstracts this away: `getAccessToken()` refreshes when expiry is within 60s.

## Reading state

    Snapshot with no network or await. Returns the current session or `null`.

    ```ts
    const session = auth.getCachedSession();
    const user = auth.getCachedUser(); // shortcut: session?.user
    ```

    **When to use:** for conditional UI ("Sign in" vs "Profile"). Don't use for backend requests — that needs `getAccessToken()`, which can refresh.

      Until `await auth.ready()` the method may return `null` even when a session is in storage. Hydration is async (especially `chrome.storage.local`), and the SDK doesn't block the constructor.

    Returns the access token, lazy-refreshes when expiry is near. `null` means signed out or refresh hit a 401.

    ```ts
    const token = await auth.getAccessToken();
    if (!token) {
      redirectToLogin();
      return;
    }
    const res = await fetch('/my-api', {
      headers: { Authorization: `Bearer ${token}` }
    });
    ```

    **When to use:** before every backend request. Don't cache the result for more than a few seconds — the SDK caches the session itself, repeat calls are cheap.

    Resolves after the session has hydrated from storage. Use on app startup to avoid a "logged out" flash for a fraction of a second.

    ```ts
    const auth = new AuthClient({ paywallId: 'pw_123' });
    await auth.ready();
    if (auth.getCachedUser()) renderApp();
    else renderLogin();
    ```

## Listening for changes

`onAuthChange` fires on every session change. The listener receives two arguments: a discriminated `event` and the `session` (or `null`).

```ts
type AuthChangeEvent =
  | 'INITIAL_SESSION'
  | 'SIGNED_IN'
  | 'SIGNED_OUT'
  | 'TOKEN_REFRESHED'
  | 'USER_UPDATED'
  | 'PASSWORD_RECOVERY';

const unsubscribe = auth.onAuthChange((event, session) => {
  if (event === 'SIGNED_IN') {
    console.log('logged in as', session?.user.email);
    showAppShell();
  } else if (event === 'SIGNED_OUT') {
    showLoginScreen();
  }
});

// on component unmount:
unsubscribe();
```

### Which event fires for what

      Event
      When

      `INITIAL_SESSION`
      Always the first callback for a new subscription — after hydration from storage. `session` may be `null` (not signed in) or a restored session.

      `SIGNED_IN`
      `signInWithEmail`, `signUp` (signed_in), `verifyOtp` (type ≠ recovery), `signInWithOAuth`, `signInAnonymously`, cross-context login.

      `SIGNED_OUT`
      `signOut`, `revokeAllSessions`, `refresh` returned 401, removal from another context.

      `TOKEN_REFRESHED`
      `refresh()` updated the tokens, same `user.id`. Cross-context rotation.

      `USER_UPDATED`
      `upgradeAnonymousToEmail` — same `user.id`, updated `email`/`is_anonymous`.

      `PASSWORD_RECOVERY`
      `verifyOtp({ type: 'recovery' })` — short-lived session for `updatePassword`. UI should show "set new password", not the regular signed-in flow.

  **Initial snapshot.** Every subscriber gets a first callback with `event = 'INITIAL_SESSION'` via a microtask after hydration resolves, **even if there's no session yet** (callback receives `null`). All subsequent callbacks are real transitions.

  That lets you safely side-effect on `event === 'SIGNED_IN'` (e.g. force-refetch) without confusing it with the page-reload restore.

## signOut

Clears local state IMMEDIATELY — no waiting for the network. Then best-effort POST to the server to revoke the refresh token.

```ts
await auth.signOut();
// auth.getCachedSession() === null
// onAuthChange fired with event='SIGNED_OUT', session=null
// storage cleared
```

  **Never throws.** Even on server 5xx or a dead network, local logout has already happened. Safe to call inside `try/finally` without your own error handler.

### Logout button

```tsx
function LogoutButton() {
  return <button onClick={() => auth.signOut()}>Sign out</button>;
}
```

No `await` needed — the UI updates via `onAuthChange` without waiting for the network round-trip.

## refresh

You usually **don't call this manually** — `getAccessToken` refreshes itself. The method is useful for rare cases:

- **Force a refresh after a backend operation that changed claims.** E.g. the user upgraded to admin and you want new roles in the access token immediately, not in an hour.
- **Tests.** A forced refresh simplifies endpoint unit tests.

```ts
auth.refresh(): Promise<AuthSession | null>
```

Returns the new session or `null` if refresh got a 401 (refresh token revoked). A network error / 5xx — propagates; the session stays; we don't sign the user out for transient issues.

### Deduplication

Parallel `getAccessToken()` + `refresh()` calls on the same `AuthClient` share **one** inflight request. Important if you fire several API calls in parallel near expiry:

```ts
// One refresh request for all three, not three parallel.
const [users, prices, offers] = await Promise.all([
  fetchUsers(),
  fetchPrices(),
  fetchOffers()
]);
```

## getAccessToken: scenarios

      State
      Behaviour
      Returns

      No session
      No network
      `null`

      Session present, &gt;60s to expiry
      No network — returns the current token
      `access_token`

      Session present, &lt;60s to expiry
      Lazy refresh on the server
      new `access_token`

      Refresh got 401
      Clears the session, emits logout
      `null`

      Refresh got a network/5xx error
      Returns the current token (still valid)
      old `access_token`

## Usage without BillingClient

If you use SDK 3.0 only for `AuthClient` (e.g. your own UI, not our `PaywallUI`) — everything works standalone. Just attach the token to your requests:

```ts

const auth = new AuthClient({ paywallId: 'pw_123' });
await auth.ready();

async function callMyApi(path: string) {
  const token = await auth.getAccessToken();
  const res = await fetch(`https://api.myapp.com${path}`, {
    headers: token ? { Authorization: `Bearer ${token}` } : {}
  });
  if (res.status === 401) {
    // The token could have been revoked between getAccessToken and the request — try refresh and retry
    const fresh = await auth.refresh();
    if (!fresh) {
      redirectToLogin();
      return;
    }
    return callMyApi(path);
  }
  return res.json();
}
```

## Persistence

The session is stored under the key `pw-<paywallId>-auth-v1` in `StorageAdapter`. By default the SDK picks:

- **Chrome Extension** — `chrome.storage.local` (visible across all extension contexts).
- **Web** — `window.localStorage`.
- **Otherwise** (Node.js, tests) — in-memory map.

You can pass your own adapter — e.g. for encrypted storage or sessionStorage:

```ts

const sessionStorageAdapter: StorageAdapter = {
  async getItem(k) { return window.sessionStorage.getItem(k); },
  async setItem(k, v) { window.sessionStorage.setItem(k, v); },
  async removeItem(k) { window.sessionStorage.removeItem(k); }
};

const auth = new AuthClient({
  paywallId: 'pw_123',
  storage: sessionStorageAdapter
});
```

  Replacing `storage` means the session **won't survive a reload** (with sessionStorage). Acceptable trade-off for private cases, but don't do it by default — frequent re-logins annoy users.

## Cross-context sync (multi-tab + Chrome Extension)

`AuthClient` listens for changes on the session key from other contexts and syncs state automatically — no manual reload or `chrome.storage.onChanged` plumbing required.

- **Web (multi-tab):** native `storage` event — sign in on one tab, others emit `onAuthChange` instantly with the new session, `getCachedSession` returns it, `getAccessToken` yields the fresh Bearer. Logout (another context called `signOut()`) also propagates — the current context signs out without a reload.
- **Chrome Extension:** via `chrome.storage.onChanged`. One login in the popup → background, content script (with `storage` permission), and the options page all receive `onAuthChange` at once.

```ts
// popup.tsx
const auth = new AuthClient({ paywallId: 'pw_123' });
const paywall = new PaywallUI({ paywallId: 'pw_123', auth });
paywall.openAuth(); // user signs in — token lands in chrome.storage.local
```

```ts
// background.ts

const auth = new AuthClient({ paywallId: 'pw_123' });
auth.onAuthChange((event, session) => {
  if (event === 'SIGNED_IN') {
    // Fires right after popup signIn
  }
});
const billing = new BillingClient({ paywallId: 'pw_123', auth });
const gateway = billing.createApiGatewayClient();
// gateway.call() will use the same Bearer the popup signed in with.
```

### Custom StorageAdapter

Replacing `storage` is supported, but if your adapter is custom — implement `watch?(key, cb)`, otherwise cross-context sync won't work (the memory fallback and custom adapters without `watch` are still OK, just no live updates):

```ts
const myStorage: StorageAdapter = {
  async getItem(k) { /* ... */ },
  async setItem(k, v) { /* ... */ },
  async removeItem(k) { /* ... */ },
  watch(key, cb) {
    // return unsubscribe; cb(null) on removal, cb(string) on update
    const unsub = mySource.on(key, cb);
    return unsub;
  }
};
```

### Teardown

On hot reload, tests or explicit reinitialization — call `destroy()`. Otherwise storage listeners outlive the instance:

```ts
auth.destroy(); // unsubscribes storage.watch, clears onAuthChange listeners
```

  In a **content script**, Bearer works the same way if the manifest has `storage` permission. To isolate the token from the content script (page is untrusted) — have the content script talk to background via `chrome.runtime.sendMessage` and let only the background do Bearer-authenticated fetches.

## Next steps

- [Error codes](/docs-v2/sdk-v3/errors) — list of `PaywallError.code` for every auth method.
- [BillingClient](/docs-v2/sdk-v3/bootstrap) — how `AuthClient` integrates with billing automatically.
- [Storage adapters](/docs-v2/sdk-v3/storage) — `StorageAdapter` details and built-in implementations.

---

# BillingClient — bootstrap and caching

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/bootstrap

`BillingClient.bootstrap()` loads the entire "structural" half of the paywall in a single round-trip: settings, prices, offers, layout, locales, and a snapshot of the current user state. This is the SDK's first network call on the page — how fast the modal becomes visible depends on it.

```ts

const paywall = new PaywallUI({ paywallId: '3', apiOrigin: 'https://api.example.com' });
await paywall.billing.bootstrap(); // 1 request, ≤1s on a cold tab
```

The SDK caches the response aggressively — for typical integrations (popup + content scripts) bootstrap rarely hits the network after that.

## What gets persisted

Bootstrap is written to the `StorageAdapter` under the key `pw-{paywallId}-bootstrap-v1`:

      Environment
      Location
      Shared across

      Chrome Extension
      `chrome.storage.local`
      popup, content scripts in every tab, service worker

      Web
      `localStorage`
      every tab on the same origin

      SSR / e2e / Node
      in-memory map
      current process only

  The `user` part of the snapshot is persisted under a separate, identity-bound key — switching accounts won't leak the previous user's state into the new session.

## Lifecycle of a single `bootstrap()`

The decision to hit the network vs return cache is made against three thresholds:

      Age of cached payload
      Behaviour
      Network requests

      ≤ 5 minutes
      Return cached **instantly**, no revalidate
      0

      5 minutes — 1 hour (stale-while-revalidate)
      Return cached instantly + background request with `?if_version=`
      1 (short 304-like response when the version is unchanged)

      &gt; 1 hour (TTL expired)
      Blocking full request
      1

      `bootstrap({ force: true })`
      Blocking request, cache ignored
      1

### Parallel calls

Two simultaneous `bootstrap()` calls (e.g. popup mount in parallel with content-script init on the same page) share one HTTP request — both callers resolve from the same response.

### Cross-context sync

Any context (popup, content script in another tab, service worker) that writes a fresh bootstrap to storage triggers `chrome.storage.onChanged` (or the `storage` event on web). Every other `BillingClient` instance gets the fresh payload **without a network request** through `StorageAdapter.watch()`.

Example: the user opens the popup → the SDK fetches bootstrap → writes it to `chrome.storage.local` → 12 open tabs with content scripts refresh their caches without an HTTP request.

## Invalidation: what the client sees after an admin edit

The backend returns a `version` hash of the structural part of the payload (settings, prices, offers, layout, locales — everything except `user`). Background revalidates send `?if_version=<v>`; on a match the backend returns a tiny `{ unchanged: true, version, user }`, so cache hits stay cheap.

The full chain from "admin clicked Save" to "user sees the change":

      Stage
      Latency
      Bottleneck

      1. DB write (platform store)
      instant
      —

      2. `revalidateTag` on the server cache (online)
      instant after fan-out from platform
      Cache fan-out across edge nodes — a partial failure can leave stale responses on a few nodes briefly

      3. Client with an **active** persisted cache (≤5 min)
      **Won't auto-refresh** — needs a new `bootstrap()` after crossing the threshold
      5-minute stale threshold

      4. Client with a **stale** cache (5min — 1h)
      UI renders from stale; 1–2s after revalidate `onBootstrapChange` swaps in fresh data
      —

      5. Client with an **expired** cache (&gt;1h) or a cold tab
      Fresh data on the next `bootstrap()`
      1-hour persist TTL

  A user who keeps the tab open and doesn't invoke `bootstrap()` again **won't see the change automatically**. The SDK doesn't push updates — there's no WebSocket/SSE. To forcibly refresh active instances, either call `paywall.billing.bootstrap({ force: true })` explicitly, or wait for the next UI mount (popup / modal open).

## API

### `bootstrap(opts?)`

```ts
billing.bootstrap(): Promise<PaywallBootstrap>;
billing.bootstrap(force: boolean): Promise<PaywallBootstrap>;        // legacy
billing.bootstrap({ force?: boolean; signal?: AbortSignal }): Promise<PaywallBootstrap>;
```

- `force: true` — ignores cache and TTL, always hits the network. Use after explicit actions that definitely changed paywall state (admin mode, hotfix flows).
- `signal` — `AbortSignal` for cancellation. Useful when unmounting a React component.

### `onBootstrapChange(cb)`

```ts
const unsubscribe = billing.onBootstrapChange((bootstrap) => {
  console.log('bootstrap updated, new version:', bootstrap.version);
  // re-render UI
});
```

Fires **only on a real `version` change**: a background revalidate that returned `unchanged: true` does not invoke the listener. Ideal for UI frameworks — no spurious re-renders.

### `getCachedBootstrap()`

```ts
billing.getCachedBootstrap(): PaywallBootstrap | null;
```

Sync access to the last loaded bootstrap. `null` means no successful request yet. Handy for post-checkout logic that needs to read `settings.success_redirect_url` without an `await`.

### `getPrices(opts?)` / `getCachedPrices()`

A shortcut over `bootstrap()` — returns the paywall's price array so the host can render pricing cards outside the modal (on a landing page, "/pricing" page, tier widget).

```ts
billing.getPrices(opts?: { force?: boolean; signal?: AbortSignal }): Promise<PaywallPrice[]>;
billing.getCachedPrices(): PaywallPrice[] | null;

// Same thing at the PaywallUI level:
paywall.getPrices(opts?): Promise<PaywallPrice[]>;
paywall.getCachedPrices(): PaywallPrice[] | null;
```

Cache semantics are identical to `bootstrap()` (5 min stale-while-revalidate + 1 hour persist TTL, in-flight dedupe). Locale overrides for `label`/`description` under `navigator.language` are applied automatically — the array is render-ready.

  Prices are part of bootstrap, so `getPrices()` doesn't fire a separate request. If bootstrap is already loaded — synchronous return from cache. If not — one network request for the whole paywall structure, after which `getCachedBootstrap()` is also populated.

  Using `@monetize.software/sdk-react`? See [`usePaywallPrices`](/docs-v2/sdk-v3/react/hooks#usepaywallprices) — it wraps `getCachedPrices` + `onBootstrapChange` with proper `useSyncExternalStore` semantics.

For subscriptions to price changes (admin updates a plan → revalidate picks up the new version) use `onBootstrapChange` — `getPrices` does not expose its own listener (that would be redundant API on the same source of truth).

### `PaywallPrice` fields

```ts
interface PaywallPrice {
  id: string;
  currency: string;          // ISO 4217: 'USD', 'EUR', ...
  amount: number;            // in minor units (cents)
  interval: 'month' | 'year' | 'week' | 'day' | 'lifetime' | null;
  interval_count: number | null;
  trial_days: number | null; // card trial: free days AFTER payment
  label?: string | null;     // override from admin / locale
  description?: string | null;
  local?: { currency: string; amount: number } | null; // geo-converted price
}
```

### `getUser(opts?)` / `getCachedUser()` / `onUserChange(cb)`

```ts
billing.getUser(opts?: { force?: boolean; signal?: AbortSignal }): Promise<PaywallUser>;
billing.getCachedUser(): PaywallUser | null;
billing.onUserChange(cb: (user: PaywallUser) => void, opts?: { immediate?: 'microtask' | 'sync' | 'none' }): () => void;
```

Returns the paywall user (`has_active_subscription` / `purchases` / `trial` / `had_previous_trial`). Uses the same persistence + stale-while-revalidate model as bootstrap, plus identity-aware storage key.

```ts
const user = await billing.getUser();
if (user.has_active_subscription) enablePremium();
```

`PaywallUser` shape — in [Events → PaywallUser](/docs-v2/sdk-v3/events#paywalluser).

### `createCheckout(params)`

Returns a checkout URL for the chosen `priceId`. Use it when you drive your own buy buttons (custom pricing page, landing-page cards, in-app "Upgrade" button) and want to redirect to the payment provider yourself — instead of opening the bundled paywall via `paywall.open()`.

```ts
billing.createCheckout(params: {
  priceId: string;
  successUrl?: string;
  errorUrl?: string;
  shopUrl?: string;
  trialDays?: number;
  /** Idempotency key — duplicate clicks on the same key return the same
   *  checkout URL. SDK generates a UUID v4 if omitted. */
  idempotencyKey?: string;
  /** Renewal/upgrade flow — passes `ignoreActivePurchase: true` to the backend
   *  so /start-checkout doesn't return 409 for an already-subscribed user. */
  ignoreActivePurchase?: boolean;
  signal?: AbortSignal;
}): Promise<CheckoutResult>;
```

```ts
interface CheckoutResult {
  url: string;
  sessionId?: string;
  acquiring?: 'stripe' | 'paddle' | 'chargebee' | 'overpay' | 'freemius';
}
```

Requires an `identity.email` (or a connected `AuthClient`). Without one — throws `identity_required`. If the user already has an active subscription the backend returns 409 + `{ hasActivePurchase: true }` — the SDK normalizes this into `PaywallError('already_purchased', { status: 409 })`. To bypass for renewal/upgrade flows, pass `ignoreActivePurchase: true`.

Parallel clicks on the same `priceId` (or `idempotencyKey`) collapse to one request — both callers get the same checkout URL.

### `getBalances(opts?)` / `getCachedBalances()` / `onBalanceChange(cb, opts?)` / `refreshBalances()` / `decrementBalanceLocal(queryType)`

Balance APIs for AI providers (`tokenization_queries`). Same persistence model as bootstrap with tighter thresholds (30s stale, 5min TTL) and identity-bound storage keys.

```ts
billing.getBalances(): Promise<Balance[]>;
billing.getCachedBalances(): Balance[] | null;
billing.onBalanceChange(cb: (balances: Balance[]) => void, opts?: { immediate?: 'microtask' | 'sync' | 'none' }): () => void;
billing.refreshBalances(): Promise<Balance[]>;
billing.decrementBalanceLocal(queryType: string | undefined): void; // optimistic
```

`Balance: { type: string; count: number }`. Details and SSE example — in [API Gateway](/docs-v2/sdk-v3/api-gateway).

### Customer portal — `getCustomerPortalUrl()` / `listPurchases()` / `cancelSubscription()`

For your own customer-portal UI ("My subscriptions" page). Bearer auth required (or a server `apiKey`).

```ts
billing.getCustomerPortalUrl(opts?: { signal?: AbortSignal }): Promise<{ url: string }>;
billing.listPurchases(opts?: { signal?: AbortSignal }): Promise<PaywallPurchaseDetailed[]>;
billing.cancelSubscription(params: {
  subscriptionId: string;
  reason: string;
  signal?: AbortSignal;
}): Promise<{ subscription: { status, canceled_at, cancel_at, cancel_at_period_end } }>;
```

See [Customer portal](/docs-v2/sdk-v3/customer-portal) for the full end-to-end pattern (list → cancel/renew → open external portal).

### `createSupportTicket(payload)`

```ts
billing.createSupportTicket(payload: {
  subject: string;
  content: string;
  email?: string;     // explicit override, otherwise identity.email
  files?: File[];     // when present, switches the request to multipart/form-data
}): Promise<{ ticket: { id: number; status: string } }>;
```

Useful when you want to drive the support form yourself instead of opening `paywall.openSupport()`. Bearer auth, if present, overrides any `email` on the backend to prevent spoofing.

### `setIdentity(identity?)` / `getIdentity()`

Manually swap the identity that BillingClient uses for headers (`X-User-Id`), checkout email and identity-bound storage keys. With a connected `AuthClient`, identity is auto-synced from `auth.user` on every `onAuthChange` — explicit `setIdentity` will be overwritten after the next auth event.

```ts
billing.setIdentity({ email: 'user@example.com', userId: 'usr_123' });
billing.getIdentity(); // → { email, userId, anonymousId } | undefined
```

### `getVisitorId()` / `getCachedVisitorId()` / `getStorage()`

Low-level helpers. `getVisitorId()` resolves the stable UUID v4 from storage (used by `EventTracker``getStorage()` exposes the `StorageAdapter` instance for callers that want to write under custom keys.

### `setBootstrap(partial)`

```ts
billing.setBootstrap(partial: Partial<PaywallBootstrap>): void;
```

Preview/editor-only setter. In `preview: true` mode the host can mutate the cached bootstrap for live preview in the admin editor. In production mode this is a no-op.

## Balances — same approach

`BillingClient.getBalances()` (AI providers × tokenization queries) uses the same model: persist + stale-while-revalidate + cross-context sync. Differences:

- **Identity-bound storage**: balances are scoped to the current identity. Calling `setIdentity` transparently rebinds the cross-context watcher to the new user's data.
- **Tighter thresholds**: 30-second stale, 5-minute persist TTL. Balance only changes after payment or an API-gateway call, so it doesn't need an hour-long TTL.
- **Optimistic updates**: `decrementBalanceLocal()` (invoked automatically after a successful `ApiGatewayClient.call()`) updates the local balance immediately. Other tabs pick up the change without an HTTP request.

      Age of cached balances
      Behaviour

      ≤ 30 seconds
      Return cached, no network

      30 seconds — 5 minutes
      Stale-while-revalidate: cached instantly + background `/balances`

      &gt; 5 minutes
      Blocking `/balances`

      `force: true`
      Blocking, cache ignored

  Unlike bootstrap, balances have **no** version/`if_version` — it's just an array of `{ type, count }`. Cross-context sync resolves conflicts by timestamp (`at`): whoever wrote latest wins.

## Cache windows

Defaults work well for Chrome extensions with a popup and content scripts running across many tabs:

- **Stale threshold — 5 minutes.** Repeated `bootstrap()` calls within this window return cached data instantly, no network.
- **Persist TTL — 1 hour.** The longest the SDK trusts a persisted payload without a fresh network check.

If you need faster reaction to admin edits, force a refresh on the actions that should reflect new state:

```ts
await paywall.billing.bootstrap({ force: true });
```

## Server-side usage

Every `BillingClient` method works headlessly. For `apiKey`-based flows (`createCheckout`, `getCustomerPortalUrl`, `createSupportTicket`), per-user Bearer (`listPurchases`, `cancelSubscription`), token credit/debit, webhook handlers, and storage adapters for Node / Edge runtimes — see [Headless / server-side](/docs-v2/sdk-v3/headless-server).

---

# Browser — custom UI

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/browser-custom-ui

You want our auth and billing infrastructure (so trials, checkout, customer portal, sessions all "just work") — but you render your **own** pricing page, login form, and gate components. The SDK gives you `BillingClient` for prices/checkout/state and `AuthClient` for login flows; you control every pixel of the UI.

```ts

const auth = new AuthClient({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN'
});

const billing = new BillingClient({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth
});

// Render your own pricing cards
const prices = await billing.getPrices();
// ... your JSX / your DOM ...

// Your "Buy" button:
async function onBuyClick(priceId) {
  if (!auth.user) {
    await auth.signInWithEmail({ email, password });
  }
  const { url } = await billing.createCheckout({ priceId, idempotencyKey: crypto.randomUUID() });
  window.location.assign(url);
}
```

## When to pick this

- You already have a strong design system and don't want to fit our paywall modal into it.
- You want your pricing page indexed for SEO (not hidden inside a modal).
- You need login UX that matches the rest of your app (your own copy, layout, A/B tests).
- You want full control over trial UX, upsell timing, customer-portal layout.
- You're selling per-request AI access from the browser without a backend ([API Gateway](/docs-v2/sdk-v3/api-gateway) — only fits this path).

## Form factors

This scenario works the same way in any browser context:

- **Web / SPA** — just `import { BillingClient } from '@monetize.software/sdk/core'` and go.
- **Chrome Extension (MV3)** — use the `/core` export in your popup, options page, or content script. Skip `@monetize.software/sdk-extension` (which is built around `PaywallUI` for the drop-in scenario) — your popup renders its own UI directly.
- **Telegram Mini App** — same as SPA. Watch bundle size; import narrowly from `/core`.

## What's in this path

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — bootstrap, prices, checkout, customer portal, identity

- [Authentication](/docs-v2/sdk-v3/auth) — AuthClient: email & password, OTP, OAuth, anonymous, session refresh

- [API Gateway](/docs-v2/sdk-v3/api-gateway) — Metered AI calls from the browser (provider keys held on our server)

  **Using React?** [React bindings](/docs-v2/sdk-v3/react) work here too. The hooks (`usePaywallPrices`, `usePaywallUser`, `usePaywallAccess`) read `BillingClient` state directly — power your custom pricing cards, gates, and dashboards without managing subscriptions yourself. You don't have to use `<PaywallButton>` / the modal if you don't want to.

## What's next

Cross-cutting features useful in this scenario:

- [Trial](/docs-v2/sdk-v3/trial) — getAccess() for feature gating, trial state in your own UI

- [Customer portal](/docs-v2/sdk-v3/customer-portal) — Build your own My Subscriptions UI with listPurchases / cancelSubscription

- [Events](/docs-v2/sdk-v3/events) — onBootstrapChange, onUserChange, onAuthChange — power your reactive UI

- [Storage adapters](/docs-v2/sdk-v3/storage) — Where the SDK persists state — defaults work, override for special cases

  **Don't want to use our auth at all?** If your app already has its own login system and you just need server-side checkout / state sync, switch to [Headless / server-side](/docs-v2/sdk-v3/headless-server) — `apiKey` + `identity` flow lets you skip our `AuthClient` entirely.

---

# Browser — drop-in Paywall UI

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/browser-paywall-ui

The fastest path. You install the SDK, drop `PaywallUI` somewhere in your app, and the ready-made paywall renders inside a Shadow DOM modal — branded from the dashboard, with built-in email / OTP / OAuth login and automatic state sync across tabs.

```ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});

document.getElementById('upgrade').addEventListener('click', () => paywall.open());

paywall.on('purchase_completed', () => unlockPremium());
```

## When to pick this

- You want a paywall **as fast as possible** — copy the snippet, configure prices/copy in the dashboard, ship.
- You're fine with our auth (email / OTP / OAuth / anonymous) — no need to integrate your own login.
- The visual surface is acceptable: brand color, layout (vertical / horizontal / compact), copy, localization — all from the dashboard.
- Your app runs in a browser context: SPA, plain HTML, Chrome extension, Telegram Mini App.

## What you don't need

- A backend — checkout, auth, trial counting all run client-side via the SDK.
- A custom checkout UI — Stripe/Paddle/Chargebee/Freemius/Overpay hosted checkout handles payment collection.
- Manual state sync — `purchase_completed` fires when the user comes back from the hosted checkout; the SDK refreshes state automatically.

## Form factors

- [PaywallUI (the main class)](/docs-v2/sdk-v3/ui) — Open / close, state machine, container customization, events

- [Chrome Extension (MV3)](/docs-v2/sdk-v3/installation#chrome-extension-mv3) — Offscreen document + shared state across popup / content scripts / service worker

  **Using React?** [React bindings](/docs-v2/sdk-v3/react) give you `<PaywallProvider>`, declarative components (`<PaywallGate>`, `<PaywallButton>`), and hooks (`usePaywall`, `usePaywallUser`) — same API, less boilerplate.

## What's next

Once `PaywallUI` is mounted, these features are wired automatically and worth knowing:

- [Trial](/docs-v2/sdk-v3/trial) — trial_blocked / trial_expired events, getAccess(), skipTrial

- [Customer portal](/docs-v2/sdk-v3/customer-portal) — Open Stripe/Paddle hosted portal in one line

- [Events](/docs-v2/sdk-v3/events) — purchase_completed, authChange, userChange — what to subscribe to

- [Locale & language](/docs-v2/sdk-v3/locale) — Auto-detection, getUserLanguage(), per-paywall locales

  **Need a custom pricing page (not the modal)?** Switch to [Browser — custom UI](/docs-v2/sdk-v3/browser-custom-ui) and use `BillingClient.getPrices()` to render your own cards.

  Want to keep the modal's checkout flow but render your own plan cards? Use [`paywall.checkout(priceId)`](/docs-v2/sdk-v3/ui#checkoutpriceid-opts) (or `<PaywallButton priceId={…}>` in React) — your cards drive the plan selection, the SDK still handles the auth-gate, popup-blocked retries and the awaiting-payment screen.

---

# Customer portal

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/customer-portal

A dedicated UI for users to manage their subscriptions outside the paywall — list active purchases, cancel/renew, view invoices, update payment methods. SDK 3.0 provides the building blocks; you wire up your own React/Vue layout.

  **Two layers.** The SDK exposes a typed customer-portal API on `BillingClient` (`listPurchases`, `cancelSubscription`, `getCustomerPortalUrl`) and you build the screens. For Stripe/Paddle/Chargebee customers we also have an acquirer-hosted portal — open it via `getCustomerPortalUrl()` when you don't need a custom UI.

## API surface

Every method below works with either a connected `AuthClient` (Bearer auth — natural for browser UI) or `apiKey` + `identity` (server-side, bring-your-own-auth). Without either path the SDK throws `identity_required` before the network call.

```ts
billing.listPurchases(opts?: { signal?: AbortSignal }): Promise<PaywallPurchaseDetailed[]>;
billing.cancelSubscription(params: {
  subscriptionId: string;
  reason: string;
  signal?: AbortSignal;
}): Promise<{
  subscription: {
    status: string | null;
    canceled_at: string | null;
    cancel_at: string | null;
    cancel_at_period_end: boolean | null;
  };
}>;
billing.getCustomerPortalUrl(opts?: {
  signal?: AbortSignal;
  returnUrl?: string;
}): Promise<{ url: string }>;
```

### `PaywallPurchaseDetailed`

```ts
interface PaywallPurchaseDetailed {
  id: string;
  status: string | null;
  cancel_at: string | null;
  cancel_at_period_end: boolean;
  canceled_at: string | null;
  created: string;
  ended_at: string | null;
  current_period_end: string | null;
  current_period_start: string | null;
  /** Price in minor units (cents). Sometimes from
   *  the base price (`* 100`); when geo-pricing applies, the local-currency amount. */
  unit_amount: number;
  currency: string;
  interval: string | null;
  /** Discount percent from the offer if applied; undefined when no offer. */
  discount?: number;
}
```

Richer shape than `PaywallUserPurchase` (the trimmed object that ships inside `bootstrap.user`). `listPurchases()` returns fresh state on each call — no edge caching — so cancel/renew UIs reflect the user's last action immediately.

## Listing subscriptions

```tsx

function SubscriptionsList() {
  const paywall = usePaywall();
  const [purchases, setPurchases] = useState<PaywallPurchaseDetailed[] | null>(null);

  useEffect(() => {
    if (!paywall) return;
    const ctrl = new AbortController();
    paywall.billing
      .listPurchases({ signal: ctrl.signal })
      .then(setPurchases)
      .catch((e) => {
        if (e.code !== 'aborted') console.error(e);
      });
    return () => ctrl.abort();
  }, [paywall]);

  if (!purchases) return <Skeleton />;
  if (purchases.length === 0) return <p>No active subscriptions.</p>;

  return purchases.map((p) => (
    <Card key={p.id}>
      <header>
        <strong>{(p.unit_amount / 100).toFixed(2)} {p.currency}</strong>
        {p.interval && <span> / {p.interval}</span>}
      </header>
      <dl>
        <dt>Status</dt>
        <dd>{p.status}</dd>
        <dt>Renews</dt>
        <dd>{p.current_period_end ?? '—'}</dd>
        {p.cancel_at && (
          <>
            <dt>Cancels at</dt>
            <dd>{p.cancel_at}</dd>
          </>
        )}
      </dl>
    </Card>
  ));
}
```

`listPurchases()` returns guest = empty list. For a "sign in to see your subscriptions" gate, check `paywall.auth?.getCachedSession()` first.

## Cancellation flow

```ts
const result = await paywall.billing.cancelSubscription({
  subscriptionId: '<id>',
  reason: 'too_expensive' // mandatory — collect via a select in your UI
});
console.log(result.subscription.cancel_at_period_end); // true on a "soft" cancel
```

`reason` is validated on the backend — common values mirror the legacy customer portal: `too_expensive`, `not_using`, `missing_features`, `found_alternative`, `temporary_pause`, `other`. Specifics depend on the acquirer.

By default the cancel happens at the end of the current period — the user keeps access until `current_period_end`. Refresh the list after success:

```tsx
async function handleCancel(subscriptionId: string, reason: string) {
  setBusy(true);
  try {
    await paywall.billing.cancelSubscription({ subscriptionId, reason });
    // Refetch so the UI shows the new cancel_at / cancel_at_period_end.
    const next = await paywall.billing.listPurchases();
    setPurchases(next);
  } finally {
    setBusy(false);
  }
}
```

  Make the user confirm before calling `cancelSubscription`. The SDK does not double-check — it forwards the call straight to the acquirer.

## Renew / Upgrade

To upgrade a plan or restart a cancelled subscription — open the paywall in renewal mode:

```ts
paywall.open({ renew: true });
```

This skips the `has_active_subscription` check (otherwise the user would land in the restored success view) and passes `ignoreActivePurchase: true` to `/start-checkout`. The acquirer creates a new subscription; the old one cancels at period end.

In a React app:

```tsx

<PaywallButton renew>Renew subscription</PaywallButton>
```

## Hosted portal (Stripe / Paddle / Chargebee)

For an acquirer-hosted portal (invoices, payment methods, billing history) — open the URL from `getCustomerPortalUrl()`:

```ts
const { url } = await paywall.billing.getCustomerPortalUrl({
  returnUrl: `${window.location.origin}/account`
});
window.open(url, '_blank');
```

The backend uses the Bearer (or server-side `apiKey`) to figure out which acquirer to query and returns a one-time login URL.

### `returnUrl`

The URL Stripe / Paddle / Chargebee will send the user back to when they hit the "Return to ..." button inside the hosted portal. Pass your app's account page — `${window.location.origin}/account` — so the user lands back in your UI, not on the underlying online-service domain.

Without an explicit `returnUrl` the backend falls back in this order:

1. `paywall_settings.shop_url` — the paywall-level default ("Shop URL" in the dashboard).
2. The paywall's `custom_domain` (`https://<your-custom-domain>/paywall/<id>/customer-portal/return`).
3. The bare online-service origin (a placeholder page useful only for the legacy v2 iframe flow).

For self-hosted apps, **set `returnUrl` explicitly** — otherwise users round-trip through the online service's domain after every portal session, which feels off-brand and exposes implementation details.

  **Freemius doesn't have a hosted portal** — `getCustomerPortalUrl()` throws `PaywallError('forbidden', { status: 403 })` for Freemius subscriptions. For Freemius users, build cancel/renew UI from `listPurchases()` + `cancelSubscription()` directly.

## Support ticket

The same screen often needs a "Contact support" button. Either use the SDK modal:

```tsx

<PaywallSupportButton>Need help?</PaywallSupportButton>
```

Or drive your own form and POST through SDK:

```ts
const { ticket } = await paywall.billing.createSupportTicket({
  subject: 'Refund request',
  content: 'Hi, I would like to cancel and request a refund...',
  // optional — overrides identity.email; Bearer auth ignores this and uses session email
  email: user.email,
  files: [pdfFile] // optional — switches to multipart/form-data
});

console.log(ticket.id, ticket.status); // numeric ID + 'open' / 'closed'
```

With Bearer auth, the backend ignores any `email` you pass and uses the session email (anti-spoofing). Without auth, `email` must be supplied — either in the payload or via `identity.email`, otherwise the backend rejects with `email_required`.

## Putting it together — full portal page

```tsx

function CustomerPortalContent() {
  const paywall = usePaywall();
  const account = usePaywallUser();
  const [purchases, setPurchases] = useState(null);

  // ... fetch via listPurchases, render cards, hook cancel/renew CTAs

  if (account.status === 'loading') return <Skeleton />;
  if (account.status === 'guest') return <SignInPrompt />;
  if (!account.user) return <Skeleton />;

  return (
    <main>
      <h1>Your subscription</h1>
      <SubscriptionsList />

      <section>
        <h2>Billing</h2>
        <button
          onClick={async () => {
            const { url } = await paywall.billing.getCustomerPortalUrl({
              returnUrl: `${window.location.origin}/account`
            });
            window.open(url, '_blank');
          }}
        >
          Manage billing on Stripe
        </button>
        <PaywallButton renew>Renew / Upgrade plan</PaywallButton>
      </section>

      <footer>
        <PaywallSupportButton>Need help?</PaywallSupportButton>
      </footer>
    </main>
  );
}

export default function CustomerPortalPage() {
  return (
    <PaywallProvider options={{ paywallId: 'pw_123', apiOrigin: 'https://pay.your-domain.com', auth: true }}>
      <CustomerPortalContent />
    </PaywallProvider>
  );
}
```

## Error handling

      Code
      Source
      What to do

      `identity_required`
      `listPurchases`, `cancelSubscription` without either an `AuthClient` or `apiKey` + `identity`
      Browser: enable `auth: true`. Server: pass `apiKey` and call `billing.setIdentity({ email, userId })` first.

      `identity_not_on_paywall`
      `listPurchases`, `cancelSubscription` (apiKey path) for an identity not linked to this paywall
      Verify the email/userId you pass; owner can only act on users that have ever interacted with the paywall.

      `identity_required`
      `getCustomerPortalUrl` without auth, apiKey, or identity
      Same — `auth: true` or pass `identity.email`.

      `forbidden` (`status: 403``getCustomerPortalUrl` for an acquirer without a hosted portal (e.g. Freemius) or with no active subscription.
      Show "no subscription to manage" or build your own cancel/renew UI.

      `aborted`
      User navigated away during the request.
      Ignore — not an error.

## See also

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — API reference for listPurchases / cancelSubscription / getCustomerPortalUrl / createSupportTicket

- [React bindings](/docs-v2/sdk-v3/react) — PaywallButton with renew, PaywallSupportButton, usePaywallUser hook

- [Headless / server-side](/docs-v2/sdk-v3/headless-server) — Driving customer portal flows from your backend with apiKey + per-user Bearer

- [Error codes](/docs-v2/sdk-v3/errors) — auth_required / identity_required / forbidden details

---

# Error codes

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/errors

Every SDK 3.0 error throws a `PaywallError` — a typed extension of `Error` with two extra fields: `code` (stable identifier) and `status` (HTTP status, if the error came from the network). This lets you write code that reacts to a specific case without parsing `message`.

```ts

try {
  await billing.createCheckout({ priceId });
} catch (e) {
  if (e instanceof QuotaExceededError) {
    paywall.open();
    return;
  }
  if (e instanceof PaywallError && e.code === 'already_purchased') {
    showRestoredView();
    return;
  }
  throw e;
}
```

## Shape

```ts
class PaywallError extends Error {
  readonly code: string;       // stable identifier — base your handling on this
  readonly status?: number;    // HTTP status when the error came from the network
  readonly cause?: unknown;    // original response body — for context-aware logic
}

class QuotaExceededError extends PaywallError {
  readonly code: 'not_enough_queries';
  readonly status: 402;
  readonly balances: Balance[];
  readonly queryType: string;
  readonly currentBalance: Balance | null;
}
```

  **`message` is not a stable API.** The SDK may change phrasing in minor releases. Branch on `code` / `status` / `instanceof` only.

## Configuration and initialization

      Code
      When
      What to do

      `invalid_config`
      `paywallId` or `apiOrigin` not passed; `apiOrigin` does not match `bootstrap.settings.custom_domain`; managed-auth call without a managed AuthClient.
      Double-check the SDK init. `apiOrigin` must be the paywall's `custom_domain` from the dashboard — not `appbox.space` and not `localhost`.

      `apikey_in_browser`
      `BillingClient` was constructed with `apiKey` in a browser context (`window.document` present). Thrown synchronously from the constructor — a server-SDK key in client code exposes your entire account.
      Move `BillingClient` to a trusted backend and read `apiKey` from env. For deliberate e2e tests injecting the key into a browser, pass `allowInsecureBrowserUsage: true` (never in production).

      `identity_required`
      A user-scoped method (`createCheckout`, `getCustomerPortalUrl`, `listPurchases`, `cancelSubscription`) was called without either a connected `AuthClient` or `apiKey` + `identity.email`/`identity.userId`.
      Browser: wire `auth: true`. Server: pass `apiKey` and call `billing.setIdentity({ email, userId })` (or set `identity` in the constructor).

      `identity_not_on_paywall`
      `listPurchases` / `cancelSubscription` (apiKey path) for an identity that's never interacted with this paywall.
      Verify the email/userId you pass; owner can only act on their own users. Cross-paywall lookup is blocked by design.

## Network and transport

      Code
      `status`
      When

      `network_error`
      —
      `fetch` could not reach the server (no internet, DNS, TLS, CORS preflight failed). The SDK does not auto-retry.

      `aborted`
      —
      The request was cancelled via `AbortSignal` (user closed the modal, host unmounted the component). Don't log it as an error — it's a user-driven cancellation.

      `http_<N>`
      4xx/5xx
      Backend returned an error without a `code` in the body — fallback to `http_${status}` (e.g. `http_500`, `http_429`). The text is in `message`, the body in `cause`.

      `upstream`
      502
      Auth backend / acquirer returned 5xx. The backend passes it through as-is, no auto-retry in the SDK.

## Auth — email & password

      Code
      `status`
      When

      `invalid_credentials`
      401
      `signInWithEmail` — wrong email or password.

      `user_already_exists` / `email_exists`
      400/422
      `signUp` — email already registered. Fall back to `signInWithEmail` for a single-screen "login or signup" UX.

      `weak_password`
      400
      `signUp` / `updatePassword` — password failed the platform's policy (min 6 chars by default).

      `not_authenticated`
      —
      `updatePassword` / `upgradeAnonymousToEmail` without an active session.

## Auth — OTP & reset

      Code
      `status`
      When

      `invalid_email`
      400
      `sendOtp` / `requestPasswordReset` — email format check failed.

      `over_email_send_rate_limit`
      429
      Too frequent `sendOtp` / `requestPasswordReset` — platform rate limit (~1/minute).

      `invalid_otp`
      401
      `verifyOtp` — wrong code, expired code, or no OTP was sent for this email. Anti-enumeration: don't distinguish in UI.

      `invalid_type`
      400
      `verifyOtp` — typo in `type` (not one of `'email' | 'recovery' | 'signup' | 'magiclink' | 'invite'`).

## Auth — OAuth

      Code
      `status`
      When

      `popup_blocked`
      —
      `signInWithOAuth` was called outside a user gesture. Show a "Sign in with Google" button and require an explicit re-click.

      `oauth_cancelled`
      —
      User closed the popup before completion. Silently return to the login screen.

      `oauth_failed`
      —
      Provider returned an error (access denied, wrong client_id). Show "Couldn't sign in, try another method".

      `oauth_timeout`
      —
      The popup didn't deliver a code within 5 minutes (user abandoned without closing).

      `oauth_unavailable`
      —
      SDK was called from Node.js or another runtime without `window` — developer bug.

      `exchange_failed`
      401
      The auth backend rejected the code (stolen-from-logs code, state typo). "Session expired, try again."

## Auth — anonymous

      Code
      `status`
      When

      `anonymous_disabled`
      403
      `signInAnonymously()` — `allow_anonymous` is off in paywall settings. Enable it in the dashboard or hide the "Continue as guest" button.

## Checkout & subscriptions

      Code
      `status`
      When / What to do

      `already_purchased`
      409
      `createCheckout` — the user already has an active subscription (the backend blocks to avoid a double charge). PaywallUI flips into the restored success view automatically. In headless code — show "you already have a subscription" and offer `getCustomerPortalUrl()`. For renewal/upgrade flows, retry with `ignoreActivePurchase: true`.

      `checkout_failed`
      —
      Emitted via `paywall.on('error', ...)` — PaywallRoot could not open the `checkoutUrl` or did not get a valid URL from the backend. Inspect `error.cause` for details.

      `no_price`
      —
      CTA button was pressed without a selected price. Happens when layout config is broken (price_grid without `priceIds`, cta_button without `priceId`). Bug in admin config.

      `forbidden`
      403
      `getCustomerPortalUrl` — no active subscription / acquirer doesn't support a portal (e.g. Freemius). Show "no subscription to manage".

## API Gateway

      Code
      `status`
      When / What to do

      `not_enough_queries` (`QuotaExceededError`
      402
      `gateway.call()` — user's quota is exhausted. The SDK already refreshes balances before throwing. PaywallUI catches it automatically and opens the upgrade modal; headless callers handle it themselves.

      `provider-disabled`
      403
      API Provider is disabled in paywall settings or `tokenization` is not configured. Configuration error.

## Visibility and trial

These are **not errors** — the SDK emits dedicated events (`visibility_blocked` / `trial_blocked`) instead of throwing. Don't `try/catch` for them, subscribe instead:

```ts
paywall.on('visibility_blocked', (v) => { /* country doesn't match */ });
paywall.on('trial_blocked', (status) => { /* trial still active */ });
```

Details in [Trial](/docs-v2/sdk-v3/trial) and [PaywallUI](/docs-v2/sdk-v3/ui).

## Low level: backend codes with originals

When the backend returns JSON with a `code` field in the body, the SDK passes it into `PaywallError.code` unchanged:

```jsonc
// HTTP 400 from the auth backend:
{ "code": "weak_password", "msg": "Password should be at least 8 characters" }
// → throw new PaywallError('weak_password', 'Password should be at least 8 characters', { status: 400, cause: <body> })
```

If there's no `code` in the body — fallback to `http_${status}`:

```jsonc
// HTTP 503 without a JSON body or without `code`:
// → throw new PaywallError('http_503', 'Service Unavailable', { status: 503, cause: <body|null> })
```

`cause` always carries the original response body (parsed JSON object or `null`) — pull out structural fields for context-aware handling:

```ts
catch (e) {
  if (e instanceof PaywallError && e.code === 'http_409') {
    const body = e.cause as { hasActivePurchase?: boolean } | null;
    if (body?.hasActivePurchase) {
      // ...special-case handling
    }
  }
}
```

## Cookbook

### Unified handler

```ts
function isUserMistake(e: unknown): boolean {
  if (!(e instanceof PaywallError)) return false;
  return [
    'invalid_credentials',
    'invalid_otp',
    'invalid_email',
    'weak_password',
    'user_already_exists',
    'email_exists',
    'oauth_cancelled',
    'popup_blocked',
    'aborted',
    'already_purchased'
  ].includes(e.code);
}

function isInfraIssue(e: unknown): boolean {
  if (!(e instanceof PaywallError)) return false;
  return e.code === 'network_error' || e.code === 'upstream' || (e.status ?? 0) >= 500;
}

try {
  await someAction();
} catch (e) {
  if (isUserMistake(e)) showInline(e);
  else if (isInfraIssue(e)) showToast('Service unavailable, please try later');
  else reportToSentry(e);
}
```

### Retry on network_error

The SDK does not auto-retry. If you need it, wrap on the host side:

```ts
async function withRetry<T>(fn: () => Promise<T>, attempts = 2): Promise<T> {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === attempts - 1) throw e;
      if (!(e instanceof PaywallError) || e.code !== 'network_error') throw e;
      await new Promise((r) => setTimeout(r, 500 * (i + 1))); // 500ms, 1s
    }
  }
  throw new Error('unreachable');
}

const session = await withRetry(() => auth.signInWithEmail({ email, password }));
```

  **Don't retry checkout operations.** `createCheckout` is already idempotent via `Idempotency-Key`, but a retry on `network_error` may land in the window where the backend has already created a session with the acquirer — and the user may see duplicates. If you must retry, use the same `idempotencyKey`, not an auto-generated one.

### Sentry / Datadog logging

```ts
function reportPaywallError(e: PaywallError, context: Record<string, unknown> = {}) {
  Sentry.captureException(e, {
    tags: { paywall_code: e.code, paywall_status: String(e.status ?? '') },
    extra: { cause: e.cause, ...context }
  });
}
```

`code` is a good grouping tag. `status` is useful for filtering "5xx only".

## Next steps

- [Events](/docs-v2/sdk-v3/events) — events that **don't** throw (`visibility_blocked`, `trial_blocked`, `purchase_failed`).
- [Security](/docs-v2/sdk-v3/security) — XSS, custom fetch, idempotency.
- [PaywallUI](/docs-v2/sdk-v3/ui) — state machine + `state.error` for rendering.

---

# Events

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/events

`PaywallUI` is a typed event emitter. Subscribe via `paywall.on(event, handler)` — the handler receives a strictly typed payload, IDE gives you autocomplete. Every `on()` returns an unsubscribe function.

```ts
const off = paywall.on('purchase_completed', ({ priceId, sessionId, restored }) => {
  if (restored) return; // user came back with an existing subscription, not a new purchase
  unlockFeature();
});

off(); // unsubscribe
```

  **Events vs state.** Events are good for one-shot side-effects (confetti, redirect, slack-ping). For rendering, use the [PaywallUI state machine](/docs-v2/sdk-v3/ui#state-machine) — it pairs naturally with `useSyncExternalStore`.

## Lifecycle of a single `open()`

A typical successful "open → purchase" flow:

```
open → ready → price_selected → checkout_started → purchase_completed → close
```

Edge paths:

- User closes the modal: `open → ready → close`.
- Trial is still active: `trial_blocked` (modal **does not open** — separate event).
- Targeting did not match: `visibility_blocked` (modal **does not open**).
- Bootstrap failed: `open → error → close`.

## Full event table

      Event
      Payload
      When

      `open`
      `void`
      Modal mounted. If bootstrap was not cached, `ready` fires after the data lands.

      `ready`
      `PaywallBootstrap`
      Bootstrap loaded, modal shows content. A good place for impression metrics.

      `price_selected`
      `{ priceId: string; price: PaywallPrice }`
      User clicked a plan but has not pressed "Pay" yet. Useful for selection analytics, not for conversion.

      `checkout_started`
      `{ priceId: string; url: string; acquiring?: Acquiring }`
      The `checkout_url` from the backend was received and opened in a new tab. `acquiring` is one of `'stripe' | 'paddle' | 'chargebee' | 'overpay' | 'freemius'`.

      `purchase_completed`
      `{ priceId: string \| null; sessionId: string \| null; restored?: boolean }`
      User came back with a successful payment (URL marker) **or** the SDK watcher detected `has_active_subscription=true`. `restored=true` means an active subscription was discovered, not a fresh purchase (good for metrics).

      `purchase_failed`
      `{ reason: string \| null }`
      User came back with an error/cancel from the provider. `reason: 'failed' | 'cancelled'`.

      `userChange`
      `PaywallUser`
      User-state changed: bootstrap snapshot, `getUser()` refresh, watcher tick. The first callback can arrive right after the constructor if there is a persisted user.

      `authChange`
      `{ event: AuthChangeEvent; session: AuthSession \| null }`
      Fires only with `auth: true` (managed-auth). See [AuthChangeEvent](/docs-v2/sdk-v3/auth/session#listening-for-changes).

      `trial_blocked`
      `TrialStatus`
      Trial is active — the modal **did not open** and the user gets through to the feature.

      `trial_expired`
      `void`
      Trial just expired and the modal is shown for the first time after expiry. Emitted once per `PaywallUI` instance lifetime.

      `visibility_blocked`
      `VisibilityStatus`
      Targeting did not match (country / device / visibility flag) — modal **did not open**.

      `error`
      `PaywallError`
      Bootstrap or checkout failed. Does not cover `purchase_failed` — payment cancel/decline has its own event.

      `close`
      `void`
      Modal closed — × button, ESC, overlay click, `paywall.close()`, or after a successful purchase + Continue.

## Payload types

### `PaywallBootstrap`

```ts
interface PaywallBootstrap {
  settings: PaywallSettings;
  prices: PaywallPrice[];
  offers: PaywallOffer[];
  layout?: Layout;
  user?: PaywallUser;
  locales?: Record<string, LocaleOverrides>;
  /** Stable content-hash of the structural part (excluding user). Used with
   *  `?if_version=` on revalidation. May be undefined on old backends. */
  version?: string;
}
```

See [BillingClient → Bootstrap](/docs-v2/sdk-v3/bootstrap) for format details.

### `PaywallUser`

```ts
interface PaywallUser {
  /** The main flag for most integrations. true if the user has an active
   *  subscription OR a paid lifetime purchase OR an active trial. */
  has_active_subscription: boolean;
  purchases: PaywallUserPurchase[];
  trial: { started_at: string | null; expires_at: string | null } | null;
  /** Whether the user ever had a trial on this paywall (including expired
   *  and cancelled). Anti-abuse flag for UI. */
  had_previous_trial: boolean;
}

interface PaywallUserPurchase {
  id: string;
  status: string | null;
  current_period_end: string | null;
  cancel_at_period_end: boolean | null;
}
```

### `TrialStatus`

```ts
type TrialStatus =
  | { mode: 'none'; blocked: false }
  | {
      mode: 'time';
      blocked: boolean;
      startedAt: number | null;    // Unix ms of the first open()
      expiresAt: number | null;    // Unix ms of expiry
      remainingMs: number;         // 0 — expired
      totalMs: number;             // payload hours × 3_600_000
    }
  | {
      mode: 'opens';
      blocked: boolean;
      remainingActions: number;    // 0 — expired
      totalActions: number;
    };
```

Discriminate by `status.mode`:

```ts
paywall.on('trial_blocked', (status) => {
  if (status.mode === 'time') {
    const minutes = Math.ceil(status.remainingMs / 60_000);
    showBanner(`${minutes} min of trial left`);
  } else if (status.mode === 'opens') {
    showBanner(`${status.remainingActions} free actions left`);
  }
});
```

### `VisibilityStatus`

```ts
interface VisibilityStatus {
  visible: boolean;
  /** Why `visible=false`. null when `visible=true`. */
  reason: 'country_not_match' | 'device_not_match' | 'disabled' | null;
  /** ISO country code (by IP). null when not resolved. */
  country: string | null;
  /** Country tier 1/2/3. null when country is not resolved. */
  tier: 1 | 2 | 3 | null;
}
```

### `AuthChangeEvent`

```ts
type AuthChangeEvent =
  | 'INITIAL_SESSION'   // first callback — hydration from storage
  | 'SIGNED_IN'         // signIn by any method
  | 'SIGNED_OUT'        // signOut, refresh failed 401, removal in another context
  | 'TOKEN_REFRESHED'   // token rotation (same user.id)
  | 'USER_UPDATED'      // upgradeAnonymousToEmail — same user.id, new email
  | 'PASSWORD_RECOVERY'; // verifyOtp(type='recovery') — recovery session
```

Full details — in [Session management](/docs-v2/sdk-v3/auth/session#listening-for-changes).

### `PaywallError`

```ts
class PaywallError extends Error {
  readonly code: string;        // see /docs-v2/sdk-v3/errors
  readonly status?: number;     // HTTP status when the error comes from the network
  readonly cause?: unknown;     // original response body — for context-aware handling
}
```

Full list of `code` values — in [Error codes](/docs-v2/sdk-v3/errors).

## Subscribe / unsubscribe

```ts
const off = paywall.on('purchase_completed', (data) => { /* ... */ });
off();                                  // unsubscribe via the returned function
paywall.off('purchase_completed', handler); // or explicitly — for named handlers
```

### React: always unsubscribe in cleanup

```tsx
useEffect(() => {
  return paywall.on('purchase_completed', () => unlockFeature());
}, [paywall]);
```

### Subscribe BEFORE or AFTER the constructor?

`PaywallUI` only emits events after `open()` — the constructor itself does not emit anything (except `userChange` through a microtask if there is a persisted user). So subscribing right after creating the instance is safe.

  **`autoDetectReturn: true` (the default)** — during construction, via `queueMicrotask`, the SDK scans the URL for `?paywall_status=paid|failed|cancelled`. If you subscribed **in the same tick**, you get the event. If your subscription is deferred (e.g. in `useEffect`), call `paywall.checkReturn()` after the subscription for critical post-purchase paths, or read the URL yourself.

## Shortcuts

The most common subscriptions have dedicated methods:

      Shortcut
      Equivalent

      `paywall.onUserChange(cb)`
      `paywall.on('userChange', cb)`

      `paywall.billing.onBootstrapChange(cb)`
      BillingClient level — fires only on `version` change.

      `paywall.billing.onBalanceChange(cb, opts?)`
      BillingClient level — AI-provider balances.

      `paywall.auth?.onAuthChange(cb)`
      AuthClient level — gives you `(event, session)` directly without a wrapper.

      `paywall.onStateChange(cb, opts?)`
      State machine — one listener instead of stitching `open`+`ready`+`close`+`error`.

## Internal analytics events

Separately from the public `on()` API, `PaywallUI` ships batch analytics to `${apiOrigin}/api/v1/paywall/<id>/events`:

```
paywall_viewed, price_selected, checkout_started, purchase_completed,
purchase_failed, paywall_closed, trial_blocked, trial_expired, visibility_blocked, error
```

Pass `analytics: false` in `PaywallUIOptions` to disable entirely. Custom endpoint / batch settings — via `analytics: { endpoint, flushIntervalMs, maxBufferSize }`. See [PaywallUIOptions.analytics](/docs-v2/sdk-v3/ui).

  For your own analytics, subscribe via `paywall.on(...)` and forward events to your analytics SDK — don't write to the built-in batch channel directly.

## Cookbook

### Conversion by acquirer

```ts
paywall.on('checkout_started', ({ acquiring, priceId }) => {
  analytics.track('checkout_started', { acquiring, price_id: priceId });
});

paywall.on('purchase_completed', ({ priceId, restored }) => {
  if (restored) return; // restored is not a conversion — don't move the counter
  analytics.track('purchase_completed', { price_id: priceId });
});
```

### Loading spinner for slow bootstrap

```ts
let loading = false;
paywall.on('open', () => { loading = true; renderSpinner(); });
paywall.on('ready', () => { loading = false; hideSpinner(); });
paywall.on('error', () => { loading = false; hideSpinner(); });
paywall.on('close', () => { loading = false; hideSpinner(); });
```

Or simpler — via `onStateChange`:

```ts
paywall.onStateChange((state) => {
  if (state.view === 'loading') showSpinner();
  else hideSpinner();
});
```

### Re-trigger restore on cross-tab sign-in

```ts
paywall.on('authChange', ({ event }) => {
  if (event === 'SIGNED_IN') {
    // SDK will refetch user on its own; for aggressive UX you can force it
    paywall.billing.getUser({ force: true });
  }
});
```

### Catch one specific purchase

`purchase_completed` fires for new purchases, restored ones, and from the watcher — fine for unlock, but bad for confetti. Dedupe by `sessionId`:

```ts
const seenSessions = new Set<string>();
paywall.on('purchase_completed', ({ sessionId, restored }) => {
  if (restored) return;
  if (!sessionId || seenSessions.has(sessionId)) return;
  seenSessions.add(sessionId);
  confetti();
});
```

## Next steps

- [PaywallUI](/docs-v2/sdk-v3/ui) — modal state, `getState()`, `onStateChange()`.
- [Error codes](/docs-v2/sdk-v3/errors) — `PaywallError.code` table.
- [BillingClient → events](/docs-v2/sdk-v3/bootstrap) — `onBootstrapChange`, `onUserChange`, `onBalanceChange`.

---

# Headless / server-side

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/headless-server

SDK 3.0 works on the server (Node, Bun, Deno, Cloudflare Workers, Edge functions) without any UI. This is the modern equivalent of the legacy "Server-Side SDK" — same endpoints, typed wrappers, and one extra surface: the metered API Gateway.

  **Backend not on a JS runtime?** (Python, Go, PHP, Ruby, .NET, Rust…) — the SDK is JS-only, but the underlying contract is plain HTTPS. See the [REST API reference](/docs-v2/sdk-v3/rest-api) for endpoint specs and `curl` examples.

  **One auth path for headless integrations: `apiKey` + `identity`.** The server-SDK key from the dashboard identifies *you* (the paywall owner); `identity.email` (or `identity.userId`) names the user you're acting on behalf of. Every server method — `createCheckout`, `getCustomerPortalUrl`, `listPurchases`, `cancelSubscription`, `createSupportTicket`, `creditTokens` / `debitTokens` — accepts this combination. You don't need to register users in monetize.software's auth.

## When you need this

- **Custom checkout UX** — your own pricing page, you create checkout sessions on the backend and redirect users.
- **Customer portal** — your own UI for cancel/renew/payment-history.
- **Metered AI billing** — your backend already talks to OpenAI/Anthropic (you own the provider keys); after each successful call, debit credits from the user's balance via `billing.debitTokens()` (and grant them with `billing.creditTokens()`).
- **Webhook fan-out** — receive Stripe/Paddle/Freemius webhooks, persist subscription state in your DB, then notify your app.
- **Server-rendered access checks** — read `has_active_subscription` in a Next.js Server Component / Remix loader.

## Install

```bash
pnpm add @monetize.software/sdk
```

Import from `core` to skip the UI bundle:

```ts

```

`core` is ≤ 8 KB gz with zero Preact dependencies — safe for Edge functions.

## API key — get one

Dashboard → **Settings** → **API keys** → **Create**. Copy the `sk_…` string; it appears once. The key is bound to your account; it can act on any paywall you own.

  **Never put `apiKey` into client code.** The SDK detects `window.document` and **throws `apikey_in_browser` from the constructor** — a server-SDK key in a bundle exposes your whole account, so a naive client integration fails loudly instead of silently leaking. Read the key from env on a trusted backend. (Deliberate e2e tests that inject the key into a browser can pass `allowInsecureBrowserUsage: true` to downgrade the throw to a `console.error` — never use it in production.)

## Initialization

For Lambda / Edge functions that live for one request — create a fresh `BillingClient` per handler:

```ts

export async function POST(req: Request) {
  const billing = new BillingClient({
    paywallId: process.env.PAYWALL_ID!,
    apiOrigin: process.env.PAYWALL_ORIGIN!,
    apiKey: process.env.MONETIZE_API_KEY!
  });

  const { url } = await billing.createCheckout({
    priceId: 'price_123',
    // ...
  });
  return Response.json({ url });
}
```

No shared state, nothing to clean up.

For a long-running Node worker — instantiate once at boot:

```ts
// src/monetize.ts

export const billing = new BillingClient({
  paywallId: process.env.PAYWALL_ID!,
  apiOrigin: process.env.PAYWALL_ORIGIN!,
  apiKey: process.env.MONETIZE_API_KEY!
});

// graceful shutdown — close before exit
process.once('SIGTERM', () => billing.destroy());
```

`BillingClient` is stateless w.r.t. users when only `apiKey` is configured — the same instance can serve every request. Call `billing.setIdentity({ email, userId })` immediately before each user-scoped method (`createCheckout`, `listPurchases`, `cancelSubscription`, `getCustomerPortalUrl`).

## Server-side billing methods

Everything in `BillingClient` works server-side. The methods that traditionally lived in the legacy "Server-Side SDK":

      SDK method
      Endpoint
      Auth

      `billing.createCheckout({...})`
      `POST /api/v1/paywall/[id]/start-checkout`
      `apiKey` (or Bearer)

      `billing.getPrices({...})`
      `GET /api/v1/paywall/[id]/bootstrap`
      public

      `billing.getCustomerPortalUrl()`
      `POST /api/v1/paywall/[id]/get-customer-portal`
      `apiKey` (or Bearer)

      `billing.createSupportTicket({...})`
      `POST /api/v1/paywall/[id]/support/ticket`
      `apiKey` (or Bearer)

      `billing.listPurchases()`
      `GET /api/v1/paywall/[id]/user`
      `apiKey` + `identity` (or Bearer)

      `billing.cancelSubscription({...})`
      `POST /api/paywall/cancel-subscription`
      `apiKey` + `identity` (or Bearer)

      `billing.creditTokens({...})` / `billing.debitTokens({...})`
      `POST /api/v1/paywall/[id]/balances`
      `apiKey` + `identity` (server-only)

### Create a checkout from your backend

```ts
const checkout = await billing.createCheckout({
  priceId: 'price_123',
  successUrl: 'https://app.example.com/success?session=__SESSION__',
  errorUrl: 'https://app.example.com/checkout-failed',
  // Identity (email + your stable userId) is set on BillingClient via
  // billing.setIdentity(...) before this call — see the Initialization section.
  idempotencyKey: crypto.randomUUID() // mandatory for production
});

return Response.redirect(checkout.url, 303);
```

With `apiKey` you can call `createCheckout` for **any** user — pass their email via `billing.setIdentity({ email })` before the call. Without identity the call throws `identity_required`.

### Get prices

```ts
const prices = await billing.getPrices();
return Response.json({ prices });
```

Locale overrides are applied automatically based on `bootstrap.settings.locale_default`. For per-user locale, pass `Accept-Language` via a custom `fetch` — or skip and resolve locale in your frontend.

### Customer portal URL

```ts
billing.setIdentity({ email: req.user.email });
const { url } = await billing.getCustomerPortalUrl();
return Response.json({ url });
```

For Stripe/Paddle/Chargebee the response is a one-time login URL to the acquirer-hosted portal. Freemius doesn't have a hosted portal — the backend returns `forbidden` (`status: 403`). See [Customer portal](/docs-v2/sdk-v3/customer-portal).

### Create a support ticket

```ts
const { ticket } = await billing.createSupportTicket({
  subject: 'Refund request',
  content: 'I would like to cancel and request a refund...',
  email: req.user.email,
  files: [pdfFile] // optional — switches to multipart/form-data
});
return Response.json({ ticketId: ticket.id });
```

Bearer auth, if present, ignores the `email` field and uses the session email (anti-spoofing). With `apiKey` only — `email` (or `identity.email`) is mandatory.

## Token credit and debit

For tokenized paywalls you can adjust a user's balance straight from your backend — **credit** tokens (a promo grant, a refund, a manual top-up) or **debit** them (your backend called OpenAI/Anthropic itself and only needs to deduct credits). Server-SDK only: a browser/Bearer client must never be able to change its own balance, so these throw `apikey_required` without an `apiKey`.

```ts
billing.setIdentity({ email: 'user@example.com' }); // or { userId: 'your-stable-id' }

// Grant 100 tokens of a query type (creates the type if the user has none yet)
const { count } = await billing.creditTokens({ type: 'gpt-4', amount: 100 });
// → { type: 'gpt-4', count: 100 } — the new balance for that type

// Debit 5 tokens — throws PaywallError('insufficient') if it would go below 0
await billing.debitTokens({ type: 'gpt-4', amount: 5 });
```

- `type` — the `token_type` from your paywall's tokenization config.
- `amount` — a positive integer. Both methods return `{ type, count }` with the **new** balance for that type.
- The change is **atomic** on the backend: a manual credit/debit won't clobber, and won't be clobbered by, concurrent `ApiGatewayClient` debits.

  **Daily-trial safe.** A credit above the daily-trial limit is **not** clawed back — the daily top-up only raises balances *up to* the trial limit, it never reduces a higher balance. So you can safely grant a user more tokens than their trial allowance.

**Errors** (thrown as `PaywallError` with these `code`s):

      `code`
      Cause

      `apikey_required`
      Called without `apiKey` (e.g. from the browser). Token changes are server-only.

      `identity_required`
      No `identity.email` / `identity.userId` set — call `setIdentity` first.

      `identity_not_found`
      No user with that email/userId has interacted with this paywall.

      `insufficient`
      A debit would drop the balance below zero. No partial debit — the balance is left unchanged.

  **Tokenized paywalls only.** Works only when the paywall has `tokenization` enabled and at least one configured `token_type`. For "regular" subscription paywalls — meaningless.

  **Legacy raw endpoint.** Pre-3.0 integrations used `POST /api/v1/withdraw-tokens` directly (raw `fetch`, `paywall_id` + `user_id` in the body, debit only). It still works for back-compat, but new integrations should use `billing.debitTokens()` / `billing.creditTokens()` — same auth model as the other server methods, with credit support and atomic updates.

### Why not `ApiGatewayClient` server-side?

The gateway exists so browser-only apps (SPA, Chrome extension, Telegram Mini App) can do metered AI without shipping `OPENAI_API_KEY` to the client. If you already have a backend, your backend has the provider keys — calling our gateway from there would just add a network hop. Talk to OpenAI/Anthropic directly and debit via `billing.debitTokens()` after success.

## Listing purchases and cancelling subscriptions

Both `listPurchases()` and `cancelSubscription()` work with `apiKey` + `identity` — pass the user's email (or your stable `userId`) and operate on them from your backend:

```ts
billing.setIdentity({ email: user.email, userId: user.id });

const purchases = await billing.listPurchases();
// purchases: PaywallPurchaseDetailed[] — rich shape with status, intervals, prices

await billing.cancelSubscription({
  subscriptionId: purchases[0].id,
  reason: 'too expensive'
});
```

The backend verifies that the identity is linked to your paywall — owner of paywall A can't query or cancel subscriptions of users who never interacted with paywall A. Across paywalls is impossible by design.

For most integrations you don't need `listPurchases` at all — webhooks (`subscription.created/updated/cancelled`) give you authoritative state in your own DB. Use `listPurchases` when you want fresh state on demand without waiting for webhook delivery (e.g., right after a checkout-success redirect).

For `cancelSubscription`, the alternative is `getCustomerPortalUrl()` — redirect the user to the acquirer's hosted portal (Stripe/Paddle/Chargebee/Overpay). Use it when you don't want to build cancel UX yourself. Freemius has no hosted portal — `getCustomerPortalUrl()` returns 403 there, so for Freemius you call `cancelSubscription()` directly.

## Server-rendered access checks

For Next.js Server Components / Remix loaders, read `has_active_subscription` directly without instantiating a UI:

```ts
// app/dashboard/page.tsx

export default async function Dashboard() {
  const user = await yourAuth.requireUser(); // your own session check
  if (!user) return <SignInPrompt />;

  const billing = new BillingClient({
    paywallId: process.env.PAYWALL_ID!,
    apiOrigin: process.env.PAYWALL_ORIGIN!,
    apiKey: process.env.MONETIZE_API_KEY!,
    identity: { email: user.email, userId: user.id }
  });

  const paywallUser = await billing.getUser();
  if (!paywallUser.has_active_subscription) return <UpgradePrompt />;

  return <PremiumDashboard />;
}
```

Most integrations have authoritative state in their own DB already (synced via webhooks) — you typically read straight from there, no SDK call needed. Use `billing.getUser()` when you want a fresh check right after the user came back from checkout, or when your webhook handler hasn't run yet.

  **No storage adapter needed in this scenario.** `apiKey` lives in env, `identity` comes from your auth per request, subscription state lives in your DB (via webhooks). The SDK's in-memory default is fine for one-shot calls and long-running workers alike. See [Storage adapters](/docs-v2/sdk-v3/storage) only if you're doing something unusual (e.g., your own caching layer).

## Webhooks

Server-side billing pairs with webhooks for source-of-truth state. Front-end events update UX, but webhooks update your DB. See:

- [Webhooks → Create](/docs-v2/webhooks/create-webhook) — endpoint setup.
- [Webhooks → Events](/docs-v2/webhooks/events) — full payload format and signing.
- [Quickstart → Web](/docs-v2/guide/sdk-v3-web#sync-subscriptions-on-your-backend) — Node/Next.js handler example.

```ts
// Minimal Node webhook handler — verify HMAC-SHA256, persist subscription

export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get('x-signature') ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.MONETIZE_WEBHOOK_SECRET!)
    .update(raw)
    .digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return new Response('bad signature', { status: 401 });
  }

  const event = JSON.parse(raw);
  switch (event.type) {
    case 'subscription.created':
    case 'subscription.updated':
      await upsertSubscription(event.data.user.email, event.data.subscription);
      break;
    case 'subscription.cancelled':
      await markCancelled(event.data.user.email);
      break;
  }
  return new Response('ok');
}
```

## Custom `fetch`

`BillingClient`, `AuthClient`, `ApiGatewayClient` all accept `fetch?: typeof fetch` — pass `undici` on Node 18 for connection pooling, or a Cloudflare-specific fetch wrapper for KV-bound logging:

```ts

const billing = new BillingClient({
  paywallId,
  apiOrigin,
  apiKey,
  fetch: undiciFetch as typeof fetch
});
```

  Custom fetch sees `X-Api-Key` and `Authorization: Bearer ...` on every request. Never pass a fetch implementation you don't fully control — and don't log `init.headers` in production.

## Error handling

Same `PaywallError` / `QuotaExceededError` taxonomy as the browser SDK. Codes most relevant to server flows:

      Code
      What happened

      `identity_required`
      `createCheckout` / `getCustomerPortalUrl` without `identity.email` (and no Bearer)

      `identity_not_on_paywall` (`status: 404``listPurchases` / `cancelSubscription` for an identity (email/userId) not linked to this paywall — owner can only act on users that interacted with the paywall.

      `already_purchased` (`status: 409``createCheckout` for a user that already has an active subscription. Retry with `ignoreActivePurchase: true` for upgrade/renewal.

      `forbidden` (`status: 403``getCustomerPortalUrl` for an acquirer without a hosted portal (Freemius) or with no active subscription

      `not_enough_queries` (`status: 402`, `QuotaExceededError``gateway.call` — quota exhausted

Full catalogue — in [Error codes](/docs-v2/sdk-v3/errors).

## Production checklist

- [ ] `apiKey` is read from a secret manager (env var, KMS, Vault) — never hardcoded.
- [ ] `apiOrigin` is your custom domain, not `appbox.space` and not a hardcoded fallback.
- [ ] Every `createCheckout` call has a fresh `idempotencyKey` (UUID v4) — protects against double-submits on flaky networks.
- [ ] Storage adapter is **per-user** when using Bearer auth in a long-running worker.
- [ ] `BillingClient.destroy()` is called on graceful shutdown (`SIGTERM`).
- [ ] Webhook handler verifies HMAC-SHA256 and is idempotent — Paddle re-sends `subscription.updated`.
- [ ] HTTPS everywhere; no plaintext `X-Api-Key` on the wire.
- [ ] CI grep check: no `apiKey` substring in the client bundle.
- [ ] Logs scrub `Authorization` and `X-Api-Key` headers before shipping to Datadog/Sentry.

## See also

- [BillingClient API](/docs-v2/sdk-v3/bootstrap) — Method-by-method reference: createCheckout, getCustomerPortalUrl, listPurchases, cancelSubscription

- [API Gateway](/docs-v2/sdk-v3/api-gateway) — Metered AI proxy, streaming, headless ApiGatewayClient with userId

- [Customer portal](/docs-v2/sdk-v3/customer-portal) — Building your own subscription management UI

- [Storage adapters](/docs-v2/sdk-v3/storage) — Redis / KV / encrypted storage for server-side persistence

- [Security](/docs-v2/sdk-v3/security) — Bearer vs apiKey vs X-User-ID, threat model, custom fetch warnings

- [Webhooks](/docs-v2/webhooks/events) — Source of truth for subscription state — signing and payload format

---

# Installation

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/installation

SDK 3.0 ships as an npm package and renders without an iframe in a Shadow DOM. For web you can also load it via ESM CDN (`esm.sh`/`unpkg`/`jsDelivr`); for Chrome extensions the only option is the bundled npm package (CWS review forbids remote code).

## Website / SPA

```bash
pnpm add @monetize.software/sdk
# or: npm i @monetize.software/sdk / yarn add @monetize.software/sdk
```

```ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN'
});

paywall.open(); // native Shadow DOM, no iframe
```

Good for landing pages and projects without a bundler — the browser pulls ESM deps itself.

```html
<script type="module">
  import { PaywallUI } from 'https://esm.sh/@monetize.software/sdk@3';

  const paywall = new PaywallUI({
    paywallId: '3',
    apiOrigin: 'https://YOUR_DOMAIN'
  });

  document.getElementById('upgrade').addEventListener('click', () => paywall.open());
</script>
```

CDN alternatives — `https://unpkg.com/@monetize.software/sdk@3/dist/index.js` or `https://cdn.jsdelivr.net/npm/@monetize.software/sdk@3/dist/index.js`.

  **Pin the major version** (`@monetize.software/sdk@3`), don't use `@latest` in production. A surprise major release will break your integration.

  **CDN is forbidden in Chrome extensions** — CWS review won't pass remote code execution. For extensions, use the bundled npm package only (see below).

## Chrome Extension (MV3)

For extensions there's a dedicated package `@monetize.software/sdk-extension`. It wraps SDK 3.0 in an **offscreen document** so a single state (auth session, bootstrap cache, trial counter, analytics) is shared across the popup, content scripts in every tab, and the service worker.

**Working reference extension:**
[github.com/monetize-software/sdk-examples/tree/main/browser-extension](https://github.com/monetize-software/sdk-examples/tree/main/browser-extension)
— full MV3 setup: SW + offscreen + popup + content-script, floating
Shadow-DOM widget, ApiGatewayClient with quota-driven auto-open, and a
two-config vite build (ESM for SW/offscreen/popup, IIFE for content).
Clone, set two env vars, `npm install && npm run build`, load `dist/`
in `chrome://extensions`.

```bash
pnpm add @monetize.software/sdk-extension preact
```

**When to use `@monetize.software/sdk-extension` vs plain `@monetize.software/sdk`:**

      Scenario
      Package

      Extension with popup + content scripts across tabs — sign-in in the popup should reflect on every tab instantly
      `@monetize.software/sdk-extension`

      Popup only, no content scripts; or only one extension page (options)
      `@monetize.software/sdk` — sufficient

### Minimal `manifest.json`

```json
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "permissions": ["offscreen", "storage"],
  "host_permissions": ["https://YOUR_DOMAIN/*"],
  "background": { "service_worker": "sw.js", "type": "module" }
}
```

Optional permissions:

- `"content_scripts"` — if you want to render the paywall on third-party pages (not just the popup).

  OAuth (Google / Apple / etc) **does not** require the `"identity"` permission — the SDK opens a popup window against your `apiOrigin` instead of using `chrome.identity`.

### `host_permissions` — what to pick

`host_permissions` control two things: where the extension can `fetch` (from offscreen / SW / content-script) and which origins the content-script can inject into (together with `content_scripts.matches`).

This is the **primary signal** for Chrome Web Store review and AV vendors (Avast/Kaspersky/Norton). The narrower `host_permissions`, the less suspicion.

      Extension host scenario
      Recommendation

      Extension already needs `<all_urls>` (recorder, all-site assistant, tool like Grammarly)
      Keep `<all_urls>`. SDK works as-is. **Note:** CWS review with `<all_urls>` goes through a manual audit and takes longer; AV vendors are more likely to flag such extensions as PUA. That's the cost of broad injection, not an SDK risk.

      Extension only talks to **your backend** and paywalls its own features (popup tool, side-panel app)
      Do **NOT** request `<all_urls>`. Your apiOrigin is enough: `["https://api.your-domain.com/*"]`. No content-script injection on every site needed.

      Hybrid — popup tool plus content script on a narrow list of domains
      Constrain `host_permissions` + `content_scripts.matches` to those domains: `["https://*.your-target.com/*", "https://api.your-domain.com/*"]`.

  **Keep `<all_urls>` only when it's genuinely needed for UX**, and be ready to justify it in the CWS "Permission justification" field. "So the paywall works" is a bad justification; the SDK itself doesn't require `<all_urls>`.

### Initializing the three contexts

```ts
// service-worker.ts

installRouter({ offscreenUrl: chrome.runtime.getURL('offscreen.html') });
```

```ts
// offscreen.ts (loaded from offscreen.html)

startOffscreenServer({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});
```

```ts
// content-script.ts (or popup.ts / options.ts)

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});
paywall.open(); // same API as plain @monetize.software/sdk
```

Under the hood, content-script `PaywallUI` is a proxy via a chrome port into the offscreen document. All network traffic, auth refresh, and storage happen in offscreen; content only paints UI.

## Telegram Mini App

Use the same `@monetize.software/sdk` you'd use on the web — a Telegram WebView is a regular browser context. Bundle size matters (Mini App start is blocked by load), so import narrowly:

```ts

```

OAuth inside Telegram has its own quirks — see [Authentication → OAuth](/docs-v2/sdk-v3/auth/oauth#telegram-mini-app).

---

# Localization and user language

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/locale

The paywall decides which language to display itself — it picks overrides from `bootstrap.locales` along a priority chain of sources. So the host app can **sync its own translations** with what the user sees in the modal, the SDK exposes a sync method `getUserLanguage()`.

## How the SDK picks the language

Each value in this chain is a candidate. The SDK walks them in order; **the first key present in `bootstrap.locales`** wins.

      Priority
      Source
      Where it comes from

      1
      `navigator.language`
      Full BCP-47 tag from the browser (`ru-RU`, `en-US`
      2
      base tag of `navigator.language`
      Part before the hyphen: `ru-RU` → `ru`, `en-US` → `en`

      3
      `settings.locale_default`
      Server-derived per user country (IP): AT→de, RU→ru, LV→en, FR→fr, others→en

If none of the candidates appear in `bootstrap.locales` — the SDK applies no overrides and renders the **base** version of layout/prices (whatever the admin entered in the platform as the default). That means: if the base layout in admin is in English and `locales` only contains `ru`, Russian users see Russian, everyone else sees the English base.

  Pricing (`currency`, `amount`) is a separate mechanism, **not** tied to language. It's chosen **only by the user's country** (IP→COUNTRY_CURRENCY_MAP), even if browser language and country language differ. That's deliberate: a user in Russia with an English browser still wants to see rubles. See the `price.local` field in `PaywallPrice`.

## API

### `getUserLanguage()`

Available on both `PaywallUI` and `BillingClient` — same thing, pick whichever is convenient:

```ts
paywall.getUserLanguage(): UserLanguageInfo;
paywall.billing.getUserLanguage(): UserLanguageInfo;
```

A sync method, no separate request — the data is already in bootstrap. Call it any time after `paywall.billing.bootstrap()` (and `tag`/`browserLanguage` are available even before bootstrap if `navigator.language` exists).

```ts
interface UserLanguageInfo {
  /** Best-guess BCP-47 tag for the host. Priority: applied → browserLanguage → countryLanguage.
   *  null — bootstrap not loaded and navigator unavailable (e.g. an early call in a SW). */
  tag: string | null;
  /** Key from bootstrap.locales the SDK actually applied to layout/prices.
   *  null = no match, base is rendered. */
  applied: string | null;
  /** navigator.language — what the browser reports. null in environments without navigator. */
  browserLanguage: string | null;
  /** Server-resolved language per user country (IP). From bootstrap.settings.locale_default. */
  countryLanguage: string | null;
}
```

### When to use which field

      Scenario
      Field

      Switch host i18n so the surrounding buttons match the paywall's language
      `tag` (or `applied`, if your translations key off every `locales` entry precisely)

      Tell apart "paywall really is in Russian" from "SDK guessed but no overrides exist"
      `applied !== null` → actually applied; `null` → SDK showed the base

      Analytics: how many users see incomplete locales (have `ru`, lack `fr`
      compare `tag` with `applied` — if different, locale fell back

      Tourist in Latvia with a Russian browser — what should your UI show
      `browserLanguage` (trust the user) vs `countryLanguage` (trust geo) — your call

## Examples

### Sync host i18n with the paywall

```ts

const paywall = new PaywallUI({ paywallId: 'pw_123', auth: true });
await paywall.billing.bootstrap();

const { tag } = paywall.getUserLanguage();
if (tag) {
  await i18n.changeLanguage(tag);
}
```

### React to changes (hot reload of paywall settings)

`onBootstrapChange` fires on revalidate when the set of locales or `locale_default` changes. Subscribe and re-compute:

```ts
paywall.billing.onBootstrapChange(() => {
  const { tag } = paywall.getUserLanguage();
  if (tag) i18n.changeLanguage(tag);
});
```

### Fallback analytics

```ts
const { tag, applied } = paywall.getUserLanguage();
analytics.track('paywall_locale', {
  shown: tag,                    // what the user sees
  matched: applied,               // override actually applied (null = base)
  fallback: tag !== applied      // true → no translation for the user's language
});
```

  `tag` is returned in the casing the source provided: `navigator.language` is usually `en-US` (Title-case region), `locale_default` from the server is lowercase (`en`). If your i18n requires strict format (`en-US` vs `en_US` vs `en`) — normalize on your side.

## What `getUserLanguage()` does **not** do

- **Does not change** the paywall language — it's a readonly snapshot. The SDK doesn't expose a setter because language is decided by the server (locale_default) and by the browser (navigator.language). If you need to force a language for testing — change the browser language or mock `navigator.language`.
- **Does not lazy-load** locales — `bootstrap.locales` arrives as one blob. If the desired language isn't in locales, the SDK won't fetch it later.
- **Does not consider** `navigator.languages[]` (the preference list). The SDK only looks at the first element via `navigator.language`. Multi-preference fallback (e.g. user with `['lv', 'ru', 'en']` should get `ru` when `lv` wasn't authored) isn't supported yet — contact support if you need it.

---

# Quickstart — zero to paywall in 5 minutes

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/quickstart

SDK 3.0 covers three scenarios with one npm package: a modal in the browser, popup/content-script in a Chrome extension, and headless calls from a server. All three share **one `paywallId`** — you don't need separate paywalls per channel.

  **Using an AI coding agent?** Feed it [`llms-sdk-v3.txt`](/llms-sdk-v3.txt) — a single-file pack with the full SDK 3.0 API and integration patterns. Cursor, Claude Code, Copilot and the like produce far more accurate code with it in context.

## Before you start

1. **A paywall is created** in the dashboard → "Paywalls" → "New Paywall". Remember the `paywallId` (the number in the URL).
2. **At least one payment processor is connected** (Stripe / Paddle / Chargebee / Freemius).
3. If you'll be using the API Gateway (metered AI calls) — also have a `providerId` (UUID from the "API Providers" section in the dashboard).

`apiOrigin` for every example is `https://YOUR_DOMAIN`. If you have a [custom domain](/docs-v2/custom-domains), substitute yours.

## Pick a scenario

Three integration paths — pick by how much UI you want to own and where your auth lives. See [Overview](/docs-v2/sdk-v3) for a side-by-side comparison.

### Drop-in PaywallUI — Web / SPA

Install the npm package, open the paywall with one line, listen for checkout success. Ready-made modal in a Shadow DOM with built-in email / OTP / OAuth login.

#### Install

```bash
pnpm add @monetize.software/sdk
# or: npm i @monetize.software/sdk
```

#### Initialize

```ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true // turns on built-in email / OTP / OAuth login
});
```

`auth: true` is enough for most integrations — the SDK creates an `AuthClient` itself, persists the session, refreshes tokens. If you already have your own `AuthClient` (or want a [hybrid identity](/docs-v2/sdk-v2/hybrid)), pass `identity` or `auth: <AuthClient>` explicitly.

#### Open the paywall

```ts
document.getElementById('upgrade-btn').addEventListener('click', () => {
  paywall.open();
});
```

Already rendering your own pricing cards and want the click to skip the plan-picker step? Use [`paywall.checkout(priceId)`](/docs-v2/sdk-v3/ui#checkoutpriceid-opts) — the modal still handles preauth signin, popup-blocked retry, and the awaiting-payment screen:

```ts
document.querySelectorAll<HTMLButtonElement>('[data-price-id]').forEach((el) => {
  el.addEventListener('click', () => paywall.checkout(el.dataset.priceId!));
});
```

#### React to the purchase

```ts
paywall.on('purchase_completed', ({ priceId, sessionId }) => {
  // update user state, unlock the feature
});

paywall.on('close', () => {
  // user closed the modal without buying
});

paywall.on('error', (err) => {
  console.error('paywall error', err);
});
```

Full event list — in the [`PaywallUI` API](/docs-v2/sdk-v3/ui#events).

  **What's next:** [BillingClient](/docs-v2/sdk-v3/bootstrap) — when you need prices and user state before opening the modal. [Authentication](/docs-v2/sdk-v3/auth) — customising the login flow.

### Chrome Extension (MV3)

The separate package `sdk-extension` wraps the SDK in an offscreen document — one auth/bootstrap state is shared across the popup, content scripts on every tab, and the service worker.

#### Install

```bash
pnpm add @monetize.software/sdk-extension preact
```

#### `manifest.json`

```json
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "permissions": ["offscreen", "storage"],
  "host_permissions": ["https://YOUR_DOMAIN/*"],
  "background": { "service_worker": "sw.js", "type": "module" }
}
```

  **Don't request `<all_urls>`** if your extension only talks to its own backend — it stretches CWS review and attracts AV vendors. Details — in [Installation → host_permissions](/docs-v2/sdk-v3/installation#host_permissions--what-to-pick).

#### Service worker — `sw.js`

```ts

installRouter({
  offscreenUrl: chrome.runtime.getURL('offscreen.html')
});
```

#### Offscreen — `offscreen.html` → `offscreen.ts`

```ts

startOffscreenServer({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});
```

All network traffic, auth refresh and storage live here. Popup / content script just paint the UI.

#### Popup / content script

```ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});

paywall.open();

paywall.on('purchase_completed', ({ priceId }) => {
  // signin/upgrade in the popup — every tab sees it via storage.watch
});
```

The API is identical to the web version — `PaywallUI` proxies calls through a chrome port into offscreen under the hood.

  **What's next:** [Installation → Chrome Extension](/docs-v2/sdk-v3/installation#chrome-extension-mv3) — why `web_accessible_resources` is NOT needed, what to do about `<all_urls>`, how to pass CWS review.

### Custom UI — your own pricing page and login

You render your own pricing cards / login form / "Buy" button; the SDK provides `BillingClient` for prices/checkout and `AuthClient` for our auth flows.

#### Install

```bash
pnpm add @monetize.software/sdk
```

#### Initialize

```ts

const auth = new AuthClient({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN'
});

const billing = new BillingClient({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth
});
```

#### Render your own pricing cards

```ts
const prices = await billing.getPrices();
// prices: [{ id, amount, currency, interval, label, ... }, ...]
// Render them however you want — your JSX, your DOM, your design system.
```

#### Wire the "Buy" button

```ts
async function onBuyClick(priceId: string) {
  if (!auth.user) {
    // Show your login UI first; once signed in, retry the call.
    return showLoginModal();
  }

  const { url } = await billing.createCheckout({
    priceId,
    idempotencyKey: crypto.randomUUID()
  });
  window.location.assign(url);
}
```

#### Gate a feature

```ts
const access = await billing.getAccess?.({}) ?? { granted: false };
if (access.granted) runFeature();
else showUpgradeBanner();
```

For React, the same flow with hooks instead of imperative calls — see [React / Next.js bindings](/docs-v2/sdk-v3/react).

  **What's next:** [BillingClient](/docs-v2/sdk-v3/bootstrap) — full method reference. [Authentication](/docs-v2/sdk-v3/auth) — every login flow. [API Gateway](/docs-v2/sdk-v3/api-gateway) — metered AI calls when you don't have a backend.

### Headless (server-side)

Your own backend, your own UI? Take only the `core` export (≤ 8 KB gz, no Preact/UI). Two typical headless scenarios:

- **A. Server-side billing** — `BillingClient` for bootstrapping prices and starting checkout from your backend.
- **B. API Gateway** — metered proxy to AI providers, balances debited automatically.

  **Not on a JS runtime?** (Python, Go, PHP, Ruby, .NET…) — see the [REST API reference](/docs-v2/sdk-v3/rest-api). Same endpoints, language-agnostic specs with `curl` examples.

#### Install

```bash
pnpm add @monetize.software/sdk
```

#### Option A: server-side billing

```ts

// `apiKey` identifies you (the paywall owner) — server-only, from the dashboard.
// `identity` binds the call to a user from YOUR auth system.
const billing = new BillingClient({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  apiKey: process.env.MONETIZE_API_KEY!,
  identity: {
    email: yourUser.email,
    userId: yourUser.id // your stable internal ID
  }
});

const bootstrap = await billing.bootstrap();
// bootstrap.prices, .settings, .locales — no identity needed for this read

const checkout = await billing.createCheckout({
  priceId: bootstrap.prices[0].id,
  idempotencyKey: crypto.randomUUID() // mandatory for production
});
// Redirect the user to checkout.url
```

  **Got your own auth?** This is the canonical pattern: `apiKey` server-side + `identity` from your user record. Every server method (`createCheckout`, `listPurchases`, `cancelSubscription`, `getCustomerPortalUrl`, support tickets) accepts this combination — no need to register users in monetize.software's auth. For state syncing, use [webhooks](/docs-v2/webhooks/events).

#### Option B: metered AI billing via `debitTokens`

You already have a backend talking to OpenAI/Anthropic with your own provider keys. After each successful call, debit credits from the user's balance:

```ts
// 1. Call the provider yourself
const aiResponse = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello' }]
});

// 2. Debit credits on success (server-SDK: apiKey + identity)
billing.setIdentity({ email: 'user@example.com' }); // or { userId: 'your-stable-id' }
const { count } = await billing.debitTokens({ type: 'standard', amount: 1 });
// throws PaywallError('insufficient') if the balance can't cover it

// Granting tokens (promo, refund, top-up) is the mirror call:
await billing.creditTokens({ type: 'standard', amount: 100 });
```

Identify the user by `email`, or by your own stable `userId` — which is the monetize.software auth user.id you get from webhook events (`subscription.created` → `data.user.id`) after the first `createCheckout` and store next to your own user record.

  **Why not `ApiGatewayClient`?** The gateway exists so **browser-only** apps can do metered AI without exposing provider keys. Your backend already has those keys; routing through us would just add a network hop. The gateway is browser/extension scope, not headless.

  **What's next:** [Headless / server-side](/docs-v2/sdk-v3/headless-server) — full server-side guide (apiKey setup, token credit/debit, webhooks, error handling). [API Gateway](/docs-v2/sdk-v3/api-gateway) — only when you don't have a backend (SPA / Chrome extension / Telegram Mini App).

## What all scenarios have in common

- **One `paywallId`** across drop-in / custom UI / headless — switch paths without migrating data.
- **One `apiOrigin`** (or one custom domain), or none at all for pure headless.
- **Unified auth model** — `AuthClient` behaves the same way in browser scenarios; headless uses `apiKey` + `identity` and gets the same outcome on the backend.
- **Identical event signatures** — `purchase_completed`, `authChange`, `userChange` have the same shape whether you're listening from `PaywallUI`, `BillingClient`, or webhooks.

## Next steps

- [Installation](/docs-v2/sdk-v3/installation) — Extended install, bundle budget, manifest, host_permissions

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — Bootstrap, cache, cross-context sync, optimistic updates

- [Authentication](/docs-v2/sdk-v3/auth) — Email/OTP/OAuth, anonymous sessions, hybrid identity

- [API Gateway](/docs-v2/sdk-v3/api-gateway) — Metered proxy to AI, balance state, quota handling

- [Events](/docs-v2/sdk-v3/events) — Full list of PaywallUI and BillingClient events

- [Headless / server-side](/docs-v2/sdk-v3/headless-server) — apiKey, per-user Bearer, token credit/debit, webhooks

---

# Components

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/react/components

Declarative wrappers over the hooks. They cover the most common patterns — 80% of integrations skip `useEffect` boilerplate. For the rest, reach for the hooks directly.

## `<PaywallGate>`

Declarative gate: `loading` → `fallback` → `children`. Powered by [`usePaywallAccess`](/docs-v2/sdk-v3/react/hooks#usepaywallaccessopts).

```tsx
<PaywallGate
  loading={<Skeleton />}
  fallback={({ open }) => <button onClick={open}>Upgrade</button>}
>
  <PremiumFeature />
</PaywallGate>
```

### Props

      Prop
      Type
      What it does

      `children`
      `ReactNode`
      Premium content. Rendered **only** when `access === 'granted'`.

      `fallback`
      `ReactNode \| ((args: BlockedRenderArgs) => ReactNode)`
      Shown when `access === 'blocked'`. The render function receives `{ result, open }` — `open()` triggers `paywall.open()`.

      `loading`
      `ReactNode`
      Shown while `getAccess()` hasn't returned (initial fetch / Provider mount). Defaults to `null`.

      `openOnBlocked`
      `boolean`
      Automatically call `paywall.open()` on blocked. Defaults to `false` — most hosts want an explicit CTA click first.

```ts
interface BlockedRenderArgs {
  result: Extract<PaywallAccessResult, { access: 'blocked' }>;
  open: () => void;
}
```

### Patterns

```tsx
<PaywallGate fallback={<UpgradeCTA />}>
  <PremiumFeature />
</PaywallGate>
```

Static fallback. The button inside `<UpgradeCTA>` calls `usePaywall().open()` itself.

```tsx
<PaywallGate openOnBlocked>
  <PremiumFeature />
</PaywallGate>
```

The modal pops up as soon as the user lands on the component. Useful for feature gates — clicking "AI summary" sends them straight to the paywall.

```tsx
<PaywallGate
  loading={<Skeleton />}
  fallback={({ open, result }) => (
    <Card>
      <h3>Pro feature locked</h3>
      <p>Your trial ended {timeSince(result.trial?.expiresAt)} ago.</p>
      <button onClick={open}>Continue with Pro</button>
    </Card>
  )}
>
  <PremiumFeature />
</PaywallGate>
```

The render function gives you access to `result` — vary the copy by `reason`.

```tsx
function PremiumFeatureGated() {
  const access = usePaywallAccess();
  const paywall = usePaywall();

  if (access.status === 'loading') return <Skeleton />;

  if (access.result.access === 'granted') {
    return <PremiumFeature />;
  }

  // Custom: show "Try trial" if the user hasn't had a trial yet
  if (!access.result.user?.had_previous_trial) {
    return <button onClick={() => paywall?.open()}>Try free</button>;
  }
  return <button onClick={() => paywall?.open()}>Upgrade</button>;
}
```

Hook directly — for non-standard branches like "different CTA depending on trial history".

  `<PaywallGate>` covers 80% of gating. For the rest, drop down to [`usePaywallAccess`](/docs-v2/sdk-v3/react/hooks#usepaywallaccessopts) — the component is deliberately not configurable for every edge case.

## `<PaywallButton>`

Sugar over `usePaywall().open()`. Renders a native `<button>` by default and forwards every HTML attribute.

```tsx
<PaywallButton className="btn-primary">
  Upgrade
</PaywallButton>
```

### Props

      Prop
      Type
      What it does

      `mode`
      `'paywall' \| 'support' \| 'signin' \| 'signup' \| 'auth'`
      What to open. `'paywall'` (default) → `open()`, `'support'` → `openSupport()`, `'signin'`/`'signup'` → `openSignin/openSignup`. `'auth'` is an alias for `'signin'`. Ignored when `priceId` is set.

      `priceId`
      `string`
      Direct checkout: when set, the click calls `paywall.checkout(priceId, opts)` and skips the layout with the plan list — the host has already picked the plan in its own UI. Overrides `mode`. See [direct checkout](#direct-checkout-priceid) below.

      `render`
      `(args: { open, ready, processing }) => ReactElement`
      Render-prop for full control over the trigger element. `processing` is true while direct-checkout (`priceId`-mode) is preparing — always false in modal-flow. When set, native `<button>` props are ignored.

      `identity` / `renew` / `skipTrial` / `skipVisibility`
      `OpenOptions`
      Forwarded into `paywall.open(opts)` (or `paywall.checkout(priceId, opts)` when `priceId` is set).

      `...rest`
      `ButtonHTMLAttributes<HTMLButtonElement>`
      `className`, `disabled`, `aria-*`, `type`, `onClick` — all forwarded onto the native `<button>`. `onClick` is composed with our open handler.

### Custom element via `render`

```tsx
<PaywallButton render={({ open, ready }) => (
  <MyFancyButton onClick={open} disabled={!ready}>
    Upgrade
  </MyFancyButton>
)} />
```

Radix-style `asChild` via render prop. Before Provider mount `ready: false` — the button should be `disabled`, otherwise the click is a no-op (no instance yet).

### Mode variants

```tsx
<PaywallButton>Upgrade</PaywallButton>                    {/* opens the paywall layout */}
<PaywallButton mode="support">Need help?</PaywallButton>  {/* openSupport() */}
<PaywallButton mode="signin">Sign in</PaywallButton>      {/* openSignin() */}
<PaywallButton mode="signup">Create account</PaywallButton> {/* openSignup() */}
```

### Renewal flow

```tsx
<PaywallButton renew>
  Renew subscription
</PaywallButton>
```

The paywall opens, skipping the `has_active_subscription` check — `createCheckout()` is called with `ignoreActivePurchase: true`. Use on the "Renew/Upgrade plan" button in the customer portal.

### Direct checkout (`priceId`
When you render your own pricing page (cards / table) and want the click to go **straight to the hosted checkout** — skipping the plan-picker step in the modal — pass `priceId`:

```tsx

function PricingCards() {
  const { prices } = usePaywallPrices();
  return prices?.map((p) => (
    <Card key={p.id}>
      <h3>{p.label}</h3>
      <PaywallButton priceId={p.id} className="btn-primary">
        Get this plan
      </PaywallButton>
    </Card>
  ));
}
```

**The button shows busy state automatically.** While the SDK is preparing the checkout (bootstrap → gates → `createCheckout`) — typically 200–500 ms — the button is `disabled` and exposes `aria-busy="true"`. No modal-flash. Once the hosted-checkout tab opens, the modal mounts directly into the `awaiting_payment` view. Use the `render` prop if you need to draw your own spinner:

```tsx
<PaywallButton
  priceId={p.id}
  render={({ open, ready, processing }) => (
    <MyFancyButton onClick={open} disabled={!ready || processing}>
      {processing ? <Spinner /> : 'Get this plan'}
    </MyFancyButton>
  )}
/>
```

What the modal still does for you, on demand:

- **Auth-gate** when `checkout_mode: 'preauth'` is configured and there's no signed-in user — the signin form appears, and after success the flow auto-resumes into `/start-checkout`.
- **Popup-blocked fallback** — if `window.open()` returned `null` (lost transient activation after async signin, aggressive mobile blockers), the modal shows an inline "Open checkout" retry under a fresh user gesture.
- **Awaiting-payment screen** — the modal stays mounted while the user pays in the new tab, with an "I've paid" verify button and "Open checkout again" recovery.

Without a modal at all:

- **Already-paid** — if the user already has an active subscription (detected via cached user, fresh bootstrap, the preauth signin, or a `409 hasActivePurchase` from the backend), the SDK emits `purchase_completed { restored: true }` and stays headless. The host surfaces that however it likes (toast, redirect, badge update via `usePaywallUser`).
- **Errors** — `error` is emitted (`identity.email` missing, bootstrap failure, `createCheckout` rejection); the modal never appears.

**Offers** (`usePaywallOffer(priceId)`) automatically thread their `offerId` into `/start-checkout` — required for `duration_minutes`-offers whose countdown lives in `clientStorage` (the backend can't validate the timer, so without an explicit `offerId` the discount would not apply on the hosted checkout).

Under the hood this calls [`paywall.checkout(priceId, opts)`](/docs-v2/sdk-v3/ui#checkoutpriceid-opts) — the same `OpenOptions` apply (`identity`, `renew`, `skipTrial`, `skipVisibility`).

  **`priceId` overrides `mode`.** A button is either a layout-opener or a direct-checkout trigger — combining both makes no sense (the host has already picked the plan), so when `priceId` is set, `mode` is ignored.

  **`mode="auth"` is retained as an alias for `'signin'`** for backwards compatibility — prefer `'signin'` in new code. For anonymous sign-in, don't use a button — call `usePaywall().signInAnonymously()` directly (headless, no modal; the host owns the loading state on its own button).

## `<PaywallSupportButton>`

Shortcut for `<PaywallButton mode="support">`. Useful for UI conventions ("Help" in a page corner).

```tsx
<PaywallSupportButton>
  Need help?
</PaywallSupportButton>
```

Takes the same HTML attributes as `<PaywallButton>`, minus `mode` (fixed) and `renew`/`skipTrial` (irrelevant for support).

## Composition: feature gate + CTA

A typical shape for a premium page:

```tsx
function AISummaryPage() {
  return (
    <main>
      <h1>AI Summary</h1>

      <PaywallGate
        loading={<Skeleton />}
        fallback={({ open }) => (
          <section>
            <p>This feature is included in Pro.</p>
            <PaywallButton>Start free trial</PaywallButton>
          </section>
        )}
      >
        <AISummaryWidget />
      </PaywallGate>

      <footer>
        <PaywallSupportButton>Help</PaywallSupportButton>
      </footer>
    </main>
  );
}
```

`<PaywallGate>` controls access, `<PaywallButton>` opens the modal, `<PaywallSupportButton>` is a separate path to support. No `useEffect` chains, everything declarative.

## SSR

All three components render safely on the server:

- `<PaywallGate>` renders the `loading` prop (or `null`) — `paywall.getAccess()` is not invoked on the server.
- `<PaywallButton>` renders a native `<button>` with `disabled` until the instance is ready.
- `<PaywallSupportButton>` — same.

After the Provider mounts on the client, `usePaywallAccess()` fires its first `getAccess()` and the tree re-renders.

## Next steps

- [Hooks](/docs-v2/sdk-v3/react/hooks) — the primitives underneath the components; use them for custom scenarios.
- [Quickstart Web](/docs-v2/guide/sdk-v3-web) — end-to-end React integration.
- [Customer portal](/docs-v2/sdk-v3/customer-portal) — list/cancel/renew without `<PaywallGate>`.

---

# Hooks

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/react/hooks

Every hook in `@monetize.software/sdk-react` is safe before the Provider mounts (returns `null` / `{ status: 'loading' }`) — they can be called in SSR without `'use client'` wrappers. They're all built on `useSyncExternalStore` or on a `useEffect` subscription to SDK events with correct cleanup.

## Summary

      Hook
      Returns
      Re-renders when

      `usePaywall()`
      `PaywallUI \| null`
      instance changes (rare)

      `usePaywallState()`
      `PaywallStateSnapshot`
      any state-machine change (open / view / error)

      `usePaywallUser()`
      `PaywallUserState` (`loading` \| `guest` \| `signed_in``userChange` + `authChange`

      `usePaywallAccess(opts?)`
      `{ status, result }`
      `userChange` + `purchase_completed`

      `usePaywallPrices()`
      `{ prices, loading, error }`
      bootstrap refresh (`ready` event)

      `usePaywallOffer(priceId)`
      `ResolvedOffer \| null`
      `ready` + 1Hz tick while the countdown is live

      `usePaywallOffers()`
      `PaywallOffer[] \| null`
      `ready` (bootstrap refresh)

      `usePaywallTrial()`
      `TrialStatus \| null`
      `trial_blocked` / `trial_expired`

      `usePaywallVisibility()`
      `VisibilityStatus \| null`
      `ready` / `visibility_blocked`

      `usePaywallEvent(event, cb)`
      —
      (subscription, doesn't trigger re-renders by itself)

## `usePaywall()`

The raw `PaywallUI` instance. `null` before the Provider mounts. Every other hook is built on top of it.

```tsx
const paywall = usePaywall();
// ...
<button onClick={() => paywall?.open()}>Upgrade</button>;
```

Use it when you need direct access to `paywall.billing` / `paywall.auth` / modal methods that aren't covered by the other hooks.

## `usePaywallState()`

Modal state: `open`, `view`, `error`. Implemented on top of `paywall.onStateChange` + `paywall.getState` via `useSyncExternalStore` — correct concurrent-rendering semantics (no tearing, snapshot stable within a single React commit) and minimal re-renders (snapshot equality by `Object.is`).

```tsx
function PaywallStatus() {
  const { open, view, error } = usePaywallState();

  if (view === 'loading') return <Spinner />;
  if (view === 'error') return <ErrorBox err={error!} />;
  if (view === 'awaiting_payment') return <p>Paying in new tab…</p>;
  return null;
}
```

`view` is one of `'loading' | 'error' | 'layout' | 'auth' | 'support' | 'awaiting_payment' | 'popup_blocked' | 'purchased' | null`. Details — in [PaywallUI → state machine](/docs-v2/sdk-v3/ui#state-machine).

Before Provider mount / on SSR it returns `{ open: false, view: null, error: null }`.

## `usePaywallUser()`

Returns a discriminated `PaywallUserState` union describing **who the current user is** from the host's point of view. The shape combines three signals — Provider readiness, the managed-auth session, and the `BillingClient` user snapshot — so the consumer can branch on a single `status` field instead of guessing what `null` means.

```ts
export type PaywallUserState =
  | { status: 'loading'; user: null; session: null }
  | { status: 'guest'; user: null; session: null }
  | {
      status: 'signed_in';
      user: PaywallUser | null;
      session: AuthSession | null;
    };
```

- **`loading`** — `<PaywallProvider>` hasn't mounted the instance yet (SSR / pre-mount / StrictMode double-mount cleanup). Render a skeleton.
- **`guest`** — there's no identity:
  - managed-auth: `paywall.auth.getCachedSession()` returned `null`;
  - hybrid (no managed-auth): bootstrap finished, but the user snapshot is empty.

  Safe to show a `<PaywallButton mode="signin">` CTA.
- **`signed_in`** — there's an identity. `user` is the latest `BillingClient` snapshot (may be `null` while `/me` is in flight after a fresh sign-in — show a skeleton, not a sign-in CTA). `session` is the managed-auth `AuthSession`, or `null` in hybrid mode.

```tsx
function Account() {
  const account = usePaywallUser();

  if (account.status === 'loading') return <Skeleton />;
  if (account.status === 'guest') return <SignInCTA />;
  if (!account.user) return <Skeleton />;

  return (
    <Profile
      email={account.user.email}
      isPro={account.user.has_active_subscription}
    />
  );
}
```

The hook subscribes to **both** `userChange` and `authChange`, so sign-in / sign-out transitions rerender consumers automatically — no manual `paywall.on(...)` wiring needed. The snapshot reference is cached internally so `useSyncExternalStore` stays loop-free.

`getCachedUser()` returns reference-stable snapshots between no-op refreshes, so React skips re-renders automatically.

## `usePaywallAccess(opts?)`

**The main hook for gating features.** Wraps `paywall.getAccess(opts)` with no side-effects: the modal isn't mounted, trial storage isn't moved. Re-fetches automatically on `userChange` and `purchase_completed`.

```tsx
export type PaywallAccessState =
  | { status: 'loading'; result: null }
  | { status: 'ready'; result: PaywallAccessResult };
```

```tsx
function PremiumGate() {
  const access = usePaywallAccess();
  const paywall = usePaywall();

  if (access.status === 'loading') return <Skeleton />;
  if (access.result.access === 'blocked') {
    return <button onClick={() => paywall?.open()}>Upgrade</button>;
  }
  return <PremiumFeature />;
}
```

`opts: GetAccessOptions` mirrors `paywall.getAccess(opts)` — `skipTrial?: boolean` / `skipVisibility?: boolean`. The hook only restarts the effect when the actual flag values change, so referential stability of `opts` is unnecessary.

`access.result.reason` narrows:

- `access === 'granted'`: `'has_subscription' | 'visibility_blocked' | 'trial_blocked'`;
- `access === 'blocked'`: `'no_subscription'`.

  Not to be confused with `<PaywallGate>` — the component that wraps `usePaywallAccess` plus loading/fallback/children rendering. See [Components → PaywallGate](/docs-v2/sdk-v3/react/components#paywallgate).

## `usePaywallPrices()`

Paywall prices for your own pricing page or cards. Initial sync read from `getCachedPrices()` + first `getPrices()` request + subscription to the `ready` event.

```tsx
export interface PaywallPricesState {
  prices: PaywallPrice[] | null;
  loading: boolean;
  error: Error | null;
}
```

```tsx
function PricingCards() {
  const { prices, loading, error } = usePaywallPrices();

  if (loading && !prices) return <Skeleton />;
  if (error) return <ErrorBox err={error} />;

  return prices?.map((p) => (
    <PriceCard key={p.id} price={p} />
  ));
}
```

Locale overrides for `label`/`description` under `navigator.language` are applied automatically.

`local: { currency, amount }` is the geo-converted price (e.g. RUB for a user in Russia), separate from the base `currency`/`amount`. Independent of browser language.

## `usePaywallTrial()`

Current `TrialStatus`. `null` until the trial has been checked (host hasn't called `open()` / `getAccess()`) or the trial is disabled in the paywall config.

```tsx
function TrialBanner() {
  const trial = usePaywallTrial();
  if (!trial?.blocked) return null;

  if (trial.mode === 'opens') {
    return <Banner>{trial.remainingActions} free actions left</Banner>;
  }

  if (trial.mode === 'time') {
    const minutes = Math.ceil(trial.remainingMs / 60_000);
    return <Banner>{minutes} min of trial left</Banner>;
  }

  return null;
}
```

Trial models in detail — in [Trial](/docs-v2/sdk-v3/trial).

## `usePaywallVisibility()`

Server-computed visibility snapshot. `null` until bootstrap loads or the backend hasn't computed visibility for this paywall yet.

```tsx
function GeoFallback({ children }) {
  const visibility = usePaywallVisibility();
  if (visibility && !visibility.visible) {
    return <SoftBlock reason={visibility.reason} country={visibility.country} />;
  }
  return children;
}
```

`reason: 'country_not_match' | 'device_not_match' | 'disabled' | null`. Useful for rendering your own fallback ("service unavailable in your country") without opening the modal.

## `usePaywallEvent(event, handler)`

Declarative subscription to an SDK event with automatic unsubscribe on unmount. Inside, the handler is held in a `useRef`, so you **don't need `useCallback`** — the subscription only rebuilds when `event` or the paywall instance changes.

```tsx
function PurchaseToast() {
  const queryClient = useQueryClient();

  usePaywallEvent('purchase_completed', ({ priceId, restored }) => {
    if (restored) return;
    toast.success(`Purchase ${priceId} complete`);
    queryClient.invalidateQueries(['user']);
  });

  return null;
}
```

All event types and payloads — in [Events](/docs-v2/sdk-v3/events).

  **`usePaywallEvent` vs `useEffect`?** `usePaywallEvent` keeps the callback fresh via a ref — your handler always sees the latest props, subscription doesn't rebuild. Manual `useEffect` + `paywall.on(...)` forces you to either `useCallback` the handler or rebuild on every render. The hook eliminates both.

## SSR notes

- On the server, `usePaywall()` is always `null`. Every hook above returns a typed fallback (`null`, `{ open: false }`, `{ status: 'loading' }`).
- `usePaywallState()` uses `useSyncExternalStore(_, _, getServerSnapshot)` — `getServerSnapshot` returns a stable `{ open: false, view: null, error: null }` reference to avoid hydration mismatch.
- Inside `<PaywallProvider>` the Provider creates `PaywallUI` only in `useEffect` (client-only) — the SDK constructor touches `window/queueMicrotask` and must not run on the server.

## Next steps

- [Components](/docs-v2/sdk-v3/react/components) — `<PaywallGate>`, `<PaywallButton>`, `<PaywallSupportButton>`.
- [Events](/docs-v2/sdk-v3/events) — types for every event subscribed to by the hooks.
- [BillingClient](/docs-v2/sdk-v3/bootstrap) — what's under `usePaywallAccess` / `usePaywallUser` / `usePaywallPrices`.

---

# REST API

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/rest-api

Everything `@monetize.software/sdk` does is a wrapper over HTTPS endpoints — this page is the language-agnostic contract for backends that can't import the SDK (Python, Go, PHP, Ruby, .NET, Rust, etc.).

  **If your backend is Node / Bun / Deno / Edge** — use the [SDK](/docs-v2/sdk-v3/headless-server). Typed wrappers, identity binding, retries and idempotency are handled for you. The REST API is the canonical contract underneath; both are equivalent.

## Base URL

```
https://YOUR_DOMAIN
```

If you have a [custom domain](/docs-v2/custom-domains) set up for the paywall, use it — that's the canonical `apiOrigin` (it's what the browser SDK uses, and what `start-checkout` falls back to when you don't pass explicit `successUrl`/`errorUrl`).

  **Pure headless without a custom domain.** Custom domain is a paywall-level setting; it isn't enforced at the REST host level. If you're integrating purely server-to-server, you don't strictly need one — pass explicit `successUrl`/`errorUrl` on every `start-checkout` (your own app's URLs) and you're set. Contact support for the system host to point your requests at.

## Authentication

Two paths, pick by where the call originates from.

### `X-Api-Key` — server-side owner key

Server-SDK key from **Dashboard → Settings → API keys**. Identifies *you* (the paywall owner) and can act on behalf of any user on your paywall(s). Used for every server-side method.

```
X-Api-Key: sk_live_...
```

  **Never expose `X-Api-Key` to clients.** It's a server-only secret — read it from env vars / a secret manager. The SDK refuses to construct in browser context with this key set.

### `Authorization: Bearer` — per-user token

Issued by monetize.software's auth (after `signInWith…` flows in the browser SDK). Identifies a single user; the backend resolves `user.id` from the token directly.

```
Authorization: Bearer eyJhbGc...
```

Bearer is the standard path for **browser** SPAs / Chrome extensions / Telegram Mini Apps where the user signed in via our `AuthClient`. For headless integrations with your own auth — use `X-Api-Key` instead.

### Identity passing (apiKey path)

When you call a user-scoped method with `X-Api-Key`, the backend needs to know **which user** you're acting on. Pass `email` and your stable `userId` in the request — the backend looks up the matching user on your paywall.

The backend additionally verifies the identity is linked to your paywall. Querying users that never interacted with your paywall returns `identity_not_on_paywall` (404). Cross-paywall lookup is blocked by design.

### Other headers

| Header | When | Notes |
|---|---|---|
| `X-Paywall-Id` | Always (set by SDK) | Same value as the `{id}` URL segment |
| `X-SDK-Version` | Optional | For our telemetry — when integrating directly, set to your client name + version |
| `Idempotency-Key` | `start-checkout` | UUID v4. Duplicate POSTs with the same key return the same checkout URL |

## Endpoints

### `GET /api/v1/paywall/{id}/bootstrap`

Returns the structural part of the paywall: settings, prices, offers, layout, locales. **Public** — no auth required for the structural payload. If you pass a Bearer token, the response also includes the user state (`user.has_active_subscription`, `purchases`).

**Request**

```
GET /api/v1/paywall/3/bootstrap
```

**Response (200)** — see [BillingClient → bootstrap shape](/docs-v2/sdk-v3/bootstrap) for the full type. Key fields:

```json
{
  "version": "sha256:abc...",
  "settings": { "id": "3", "name": "Upgrade to Pro", "brand_color": "#000", ... },
  "prices": [
    {
      "id": "monthly",
      "currency": "USD",
      "amount": 9.99,
      "interval": "month",
      "interval_count": 1,
      "trial_days": 7,
      "label": "Monthly",
      "local": { "currency": "EUR", "amount": 9.49 }
    }
  ],
  "offers": [...],
  "layout": { "type": "modal", "blocks": [...] },
  "locales": { "en": {...}, "es": {...} }
}
```

**curl**

```bash
curl https://YOUR_DOMAIN/api/v1/paywall/3/bootstrap
```

### `POST /api/v1/paywall/{id}/start-checkout`

Creates a checkout session with the configured payment processor and returns its hosted URL. Redirect your user there.

**Headers**

```
Content-Type: application/json
X-Api-Key: sk_live_...        (or Authorization: Bearer ...)
Idempotency-Key: <uuid-v4>    (mandatory for production)
```

**Body**

```json
{
  "email": "user@example.com",
  "priceId": "monthly",
  "successUrl": "https://app.example.com/success?session=__SESSION__",
  "errorUrl": "https://app.example.com/checkout-failed",
  "shopUrl": "https://app.example.com/pricing",
  "trial_days": null,
  "ignoreActivePurchase": false,
  "userMeta": { "source": "email_campaign_q2" },
  "localCurrency": "EUR"
}
```

- `email` — required in apiKey path. Ignored in Bearer path (server reads it from the token).
- `priceId` — required. Get it from `bootstrap.prices[].id`. **Don't hardcode it** — price IDs are dynamic and change when pricing is edited, the payment processor is switched, or a plan is recreated. Always read the current value from `bootstrap` at runtime; a stale hardcoded ID returns `404`.
- `successUrl`/`errorUrl` — optional overrides. Default to `settings.success_redirect_url` from the dashboard.
- `trial_days` — optional override on the price-level trial.
- `ignoreActivePurchase` — pass `true` for renew/upgrade flows; otherwise the backend returns `409` if the user already has an active subscription.
- `userMeta` — JSON metadata stored against the user's row on this paywall.
- `localCurrency` — ISO 4217 hint for geo pricing (the backend may override based on its own GeoIP).

**Response (200)**

```json
{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
  "userId": "auth-uuid",
  "acquiring": "stripe"
}
```

`acquiring` is one of `stripe`, `paddle`, `chargebee`, `freemius`, `overpay`.

**Errors**

| Status | Code / payload | When |
|---|---|---|
| 400 | `Missing required parameters: email, priceId` | Missing fields |
| 400 | `Invalid successUrl format` etc. | URL doesn't match `https?://` |
| 401 | `Invalid API key` | Bad `X-Api-Key` |
| 403 | `Access denied: API key owner does not match paywall owner` | Key belongs to a different account |
| 409 | `{ hasActivePurchase: true }` | User already has an active sub; retry with `ignoreActivePurchase: true` |

**curl**

```bash
curl -X POST https://YOUR_DOMAIN/api/v1/paywall/3/start-checkout \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MONETIZE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "user@example.com",
    "priceId": "monthly",
    "successUrl": "https://app.example.com/success"
  }'
```

### `GET /api/v1/paywall/{id}/user`

Returns the user's purchases, balances, trial state, and computed geo-targeting for this paywall.

**Headers**

```
X-Api-Key: sk_live_...        (or Authorization: Bearer ...)
```

**Query (apiKey path only)**

| Param | Required | Notes |
|---|---|---|
| `email` | one of two | Email of the user you're querying |
| `user_id` | one of two | The user id returned by webhook events / by `start-checkout` response |

In Bearer path, identity comes from the token — query params are ignored.

**Response (200)** — full shape in [BillingClient docs](/docs-v2/sdk-v3/bootstrap#getuser). Key fields:

```json
{
  "user": { "id": "...", "email": "...", "name": "...", "created_at": "..." },
  "tier": 1,
  "country": "US",
  "balances": [{ "type": "standard", "count": 42 }],
  "countryMatch": true,
  "purchases": [
    {
      "id": "sub_123",
      "status": "active",
      "interval": "month",
      "unit_amount": 999,
      "currency": "USD",
      "current_period_end": "2026-06-29T...",
      "cancel_at_period_end": false
    }
  ],
  "paid": true,
  "trial": null,
  "meta": { ... }
}
```

In apiKey path, the `user` field is `undefined` — use `purchases`, `paid`, and `balances` instead. The `user` object is only populated in the Bearer path (where the auth session carries the profile).

**Errors**

| Status | Code | When |
|---|---|---|
| 400 | `identity_required` | apiKey without `?email=` or `?user_id=` |
| 401 | `Unauthorized` | No Bearer and no apiKey |
| 404 | `identity_not_found` | Email/userId doesn't exist in our system |
| 404 | `identity_not_on_paywall` | Identity exists but never interacted with this paywall |

**curl**

```bash
# apiKey path
curl "https://YOUR_DOMAIN/api/v1/paywall/3/user?email=user@example.com" \
  -H "X-Api-Key: $MONETIZE_API_KEY"
```

### `POST /api/paywall/cancel-subscription`

Cancels a subscription at the end of the current billing period (acquirer-side). The DB is updated when the corresponding webhook arrives; the response carries a synthetic shape for immediate UI feedback.

**Note the path** — this endpoint lives under `/api/paywall/` (not `/api/v1/paywall/`).

**Headers**

```
Content-Type: application/json
X-Api-Key: sk_live_...        (or Authorization: Bearer ...)
```

**Body**

```json
{
  "subscriptionId": "sub_123",
  "paywallId": "3",
  "cancellationReason": "too expensive",
  "email": "user@example.com",
  "userId": "your-internal-id"
}
```

- `subscriptionId` — required. From `listPurchases()[].id` or your DB (synced via webhooks).
- `paywallId` — required in apiKey path (used for cross-paywall protection). Ignored in Bearer path.
- `cancellationReason` — required. Non-empty string.
- `email` / `userId` — required in apiKey path (one of). Identity of the subscription owner.

**Response (200)**

```json
{
  "success": true,
  "message": "Subscription cancelled successfully",
  "subscription": {
    "id": "sub_123",
    "status": "active",
    "cancel_at_period_end": true,
    "cancel_at": "2026-06-29T00:00:00.000Z",
    "canceled_at": null
  }
}
```

**Errors**

| Status | Code | When |
|---|---|---|
| 400 | `identity_required` | apiKey without `paywallId` / email / userId |
| 400 | `Subscription is already cancelled` | Idempotency: the sub was already cancelled |
| 403 | `Unauthorized` | Bearer absent and apiKey absent (or anonymous Bearer) |
| 404 | `identity_not_on_paywall` | apiKey path: identity exists but not on this paywall |
| 404 | `Subscription not found` | `subscriptionId` doesn't match `(user_id, paywall_id)` |

**curl**

```bash
curl -X POST https://YOUR_DOMAIN/api/paywall/cancel-subscription \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MONETIZE_API_KEY" \
  -d '{
    "subscriptionId": "sub_123",
    "paywallId": "3",
    "cancellationReason": "too expensive",
    "email": "user@example.com"
  }'
```

### `POST /api/v1/paywall/{id}/get-customer-portal`

Returns a one-time URL to the acquirer-hosted customer portal (Stripe / Paddle / Chargebee / Overpay). Freemius does not provide a hosted portal — this endpoint returns `403` with `{ isTest }` instead.

**Headers**

```
Content-Type: application/json
X-Api-Key: sk_live_...        (or Authorization: Bearer ...)
```

**Body (apiKey path)**

```json
{
  "email": "user@example.com",
  "userMeta": { "source": "..." }
}
```

In Bearer path, both fields are ignored; identity is taken from the token.

**Response (200)**

```json
{ "url": "https://billing.stripe.com/p/session/test_..." }
```

**Errors**

| Status | Code | When |
|---|---|---|
| 400 | `Email is required` | apiKey path, body missing email |
| 401 | `invalid_token` | Bearer present but invalid |
| 403 | `{ isTest: "1" or "0" }` | Acquirer (e.g. Freemius) has no hosted portal, or the user has no active sub |

**curl**

```bash
curl -X POST https://YOUR_DOMAIN/api/v1/paywall/3/get-customer-portal \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MONETIZE_API_KEY" \
  -d '{ "email": "user@example.com" }'
```

### `POST /api/v1/paywall/{id}/support/ticket`

Creates a support ticket on behalf of a user. Two transports — JSON for text only, multipart for attachments (images up to 10 MB each, max 5 files; MIME: `image/jpeg`, `image/png`, `image/webp`).

**Auth** — `Authorization: Bearer` (recommended) or unauthenticated guest with `customer_email` in the body.

**JSON body**

```json
{
  "subject": "Refund request",
  "content": "I would like to cancel and request a refund...",
  "customer_email": "user@example.com"
}
```

- `subject` — required, 3–200 chars.
- `content` — required, 1–5000 chars.
- `customer_email` — required for guests. Ignored if Bearer is present (server uses the session email — anti-spoofing).

**Multipart body** — same fields plus `files`:

```
files: <File>
files: <File>
```

**Response (200)**

```json
{ "ticket": { "id": 12345, "status": "open" } }
```

**Errors**

| Status | Code | When |
|---|---|---|
| 400 | `invalid_payload` | Missing `subject` or `content` |
| 400 | `subject_length` / `content_length` | Outside bounds |
| 400 | `email_required` | Guest without `customer_email` |
| 400 | `too_many_files`, `invalid_file` | Multipart constraints |
| 429 | `rate_limit_exceeded` | More than 2 tickets per 24 h per user/email |

**curl**

```bash
curl -X POST https://YOUR_DOMAIN/api/v1/paywall/3/support/ticket \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $USER_BEARER" \
  -d '{
    "subject": "Refund request",
    "content": "I would like to cancel..."
  }'
```

### `POST /api/v1/paywall/{id}/balances`

Credit **or** debit a user's token balance for a tokenized paywall. This is the SDK 3.0 way (preferred over the legacy `/api/v1/withdraw-tokens` below) — it backs `billing.creditTokens()` / `billing.debitTokens()`. Use it to grant tokens (promo, refund, manual top-up) or to debit after your backend called an AI provider itself.

**Auth** — `X-Api-Key` only (server-side). Bearer is **not** accepted: a user must never be able to change their own balance.

**Headers**

```
Content-Type: application/json
X-Api-Key: sk_live_...
```

**Body** — identify the user by `email` or `user_id` (same identity model as the other v1 endpoints; the user must be linked to this paywall):

```json
{
  "email": "user@example.com",
  "type": "gpt-4",
  "amount": 100,
  "op": "credit"
}
```

- `email` *or* `user_id` — required (one of). `user_id` is the monetize.software auth `user.id`.
- `type` — required. Must match a `tokenization_queries[].type` configured on the paywall.
- `amount` — required, positive integer.
- `op` — required: `"credit"` (add) or `"debit"` (subtract).

The change is **atomic** on the backend (no lost updates vs concurrent `api-gateway` debits). A credit above the daily-trial limit is **not** clawed back — the daily trial top-up only raises balances up to the limit, never reduces a higher one.

**Response (200)**

```json
{
  "success": true,
  "user_id": "auth-uuid",
  "type": "gpt-4",
  "count": 142,
  "balances": [{ "type": "gpt-4", "count": 142 }]
}
```

`count` is the new balance for `type`.

**Errors** — JSON `{ error, code }`:

| Status | `code` | When |
|---|---|---|
| 400 | `insufficient` (+ `available`) | A debit would drop below 0 — balance left unchanged |
| 400 | `invalid_op` / `invalid_amount` / `type_required` | Bad body |
| 401 | — | `X-Api-Key` missing/invalid |
| 403 | — | Key owner is not the paywall creator |
| 404 | `identity_not_found` | No user with that `email`/`user_id` linked to this paywall |

**curl**

```bash
# credit 100 tokens
curl -X POST https://YOUR_DOMAIN/api/v1/paywall/3/balances \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MONETIZE_API_KEY" \
  -d '{ "email": "user@example.com", "type": "gpt-4", "amount": 100, "op": "credit" }'

# debit 5 tokens
curl -X POST https://YOUR_DOMAIN/api/v1/paywall/3/balances \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MONETIZE_API_KEY" \
  -d '{ "user_id": "auth-uuid", "type": "gpt-4", "amount": 5, "op": "debit" }'
```

### `POST /api/v1/withdraw-tokens`

  **Legacy.** Predates SDK 3.0 — debit-only, with `paywall_id` + `user_id` in the body. Still supported for back-compat, but new integrations should use `POST /api/v1/paywall/{id}/balances` above (credit + debit, atomic, identity by email/userId).

Debits credits from a user's balance for a tokenized paywall. Use this when your backend calls AI providers directly (your own OpenAI/Anthropic keys) and only needs to charge after a successful response.

**Auth** — `X-Api-Key` only. Bearer not accepted on this endpoint.

**Headers**

```
Content-Type: application/json
X-Api-Key: sk_live_...
```

**Body** — note `snake_case`:

```json
{
  "paywall_id": "3",
  "user_id": "auth-uuid",
  "tokens": 1,
  "token_type": "standard"
}
```

- `paywall_id` — required.
- `user_id` — required. **This is the monetize.software auth user.id**, not your own internal id. Get it from the `subscription.created` webhook (`event.data.user.id`) after the user goes through `start-checkout` for the first time, and store it alongside your own user row.
- `tokens` — required, > 0.
- `token_type` — optional, default `standard`. Must match a `tokenization_queries[].type` configured on the paywall.

**Response (200)**

```json
{ "success": true, "remaining": 41 }
```

**Errors**

| Status | Code | When |
|---|---|---|
| 400 | `Insufficient tokens` + `{ available, requested }` | Balance not enough |
| 400 | `Token type X not found in user balance` | Wrong `token_type` |
| 401 | `Invalid API key` | Bad / missing key |
| 403 | `Unauthorized. You are not the owner of this paywall` | Key belongs to a different account |
| 404 | `No balance found for this user and paywall` | The user has no balance on this paywall yet (e.g., hasn't completed a tokenized checkout or trial) |

**curl**

```bash
curl -X POST https://YOUR_DOMAIN/api/v1/withdraw-tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $MONETIZE_API_KEY" \
  -d '{
    "paywall_id": "3",
    "user_id": "auth-uuid",
    "tokens": 1,
    "token_type": "standard"
  }'
```

## Idempotency

Only `start-checkout` requires explicit idempotency — pass a UUID v4 in `Idempotency-Key`. Duplicate requests with the same key (within ~24 h) return the same `checkoutUrl` without a second call to the payment processor. Without the header the SDK auto-generates one, but a direct REST caller should send one to protect against double-submits on flaky networks.

`cancelSubscription` is naturally idempotent on the acquirer side — sending the same cancellation twice has no effect; the second call returns `400 Subscription is already cancelled`.

The balance endpoints (`POST /api/v1/paywall/{id}/balances` and the legacy `withdrawTokens`) are **not** idempotent — every call credits/debits. Build your own dedup if your retry logic needs it (e.g., store an `idempotency_key` next to each AI-call record in your DB and skip the adjustment if it's already there).

## Webhooks

State-of-truth syncing — your backend receives signed events when payments/subscriptions change. Full payload format and signature verification:

- [Webhook events](/docs-v2/webhooks/events) — Full payload reference for subscription.*, payment.*, refund.*

- [Create a webhook](/docs-v2/webhooks/create-webhook) — Endpoint setup and HMAC secret management

## Error format

All errors return JSON:

```json
{ "error": "code_or_short_message", "message": "Human-readable detail (optional)" }
```

Some endpoints return additional fields (e.g. `hasActivePurchase`, `available`, `requested`). Status codes follow standard HTTP semantics — `400` for validation, `401` for missing/invalid auth, `403` for not-owner / forbidden, `404` for not-found, `409` for conflicts, `429` for rate limits, `5xx` for unexpected server errors.

## SDK reference (when you can use it)

If you're on a JS runtime (Node / Bun / Deno / Edge / Workers) — these are the same endpoints typed and wrapped:

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — bootstrap, createCheckout, listPurchases, cancelSubscription, getCustomerPortalUrl, support tickets

- [Headless / server-side](/docs-v2/sdk-v3/headless-server) — apiKey + identity pattern, creditTokens/debitTokens, webhook handler, per-user storage

- [Customer portal](/docs-v2/sdk-v3/customer-portal) — Building your own My Subscriptions UI on top of these endpoints

---

# Security

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/security

SDK 3.0 is designed for public clients — browsers, Chrome extensions, Telegram Mini Apps. This page covers defensive assumptions, known trade-offs, and best practices for integrators.

## Threat model

What we defend against:
- Charging other people's accounts / draining their quotas (defended via Bearer resolution on the backend).
- Forged checkout URLs (server-driven, the SDK doesn't sign anything).
- Cross-popup OAuth attacks (PKCE state nonce + popup-name matching).

What we don't defend against:
- XSS on the host page — if an attacker runs JS in your origin, the tokens are theirs (see below).
- Reverse engineering the bundle — it's public code; any "API key" hardcoded inside is useless (the server-side `apiKey` option throws `apikey_in_browser` if it ever reaches a browser, so it can't end up in a bundle by accident).
- Attacks on the platform's auth backend — out of scope for the SDK.

## Token storage and XSS

By default `AuthClient` stores `access_token` and `refresh_token` in `localStorage` (web) or `chrome.storage.local` (extension). This is a deliberate trade-off:

      Approach
      For
      Against

      **localStorage** (default)
      Survives reloads, works in Chrome extensions, no cookie issues with SameSite/iframe
      Available to any JS on the page → XSS leaks it

      HttpOnly cookies
      JS can't see the token; XSS won't leak it immediately
      Doesn't work in Chrome extensions; cross-origin headaches; SDK 3.0 is intentionally cookie-free

      sessionStorage
      Doesn't survive reload (smaller attack window)
      User logs in again on every new tab — UX hurt

      In-memory only
      Minimum attack surface
      Reload = logout, useless for most SaaS

**Mitigations built into the SDK:**

1. **Refresh-token rotation on the backend** — every successful refresh invalidates the previous refresh token. A leaked refresh token is likely already invalid by the time the attacker uses it (if the victim refreshed at least once after the leak).
2. **Short access-token lifetime** — 1 hour. A leaked access token can't be extended without the refresh token.
3. **`destroy()` on teardown** — on hot reload / SPA route changes, storage subscriptions are removed so no dangling references hold stale tokens.

**What the host should do:**

1. **CSP** — `Content-Security-Policy: script-src 'self' <whitelist>` blocks unknown JS injection (the main XSS vector).
2. **Subresource integrity for CDN scripts** — if you use `<script src="https://cdn.example.com/...">`, add `integrity="sha256-..."` so a CDN compromise can't inject an XSS payload.
3. **Sanitize user-generated content** — never render `innerHTML` without `DOMPurify`, never use `dangerouslySetInnerHTML` without validation.
4. **Secure cookies for your own backend** — Bearer in SDK 3.0 is for OUR API. For YOUR API calls use your own auth (cookies/session).

```ts

// Replace storage with in-memory — for high-security environments (enterprise).
// The user will log in on every page load — this is a compromise.
const memoryStorage: StorageAdapter = (() => {
  const m = new Map<string, string>();
  return {
    async getItem(k) { return m.get(k) ?? null; },
    async setItem(k, v) { m.set(k, v); },
    async removeItem(k) { m.delete(k); }
  };
})();

const auth = new AuthClient({
  paywallId: 'pw_123',
  storage: memoryStorage
});
```

## Bearer vs API key vs X-User-ID

      Method
      Where to use
      SDK check

      **Bearer** (`AuthClient`
      Browser, extension — the main path. Backend resolves user.id securely from the token; can't be spoofed.
      None — this is the safe default.

      **`apiKey`**
      **Server-side only** (Node, Deno, Bun, Edge). Server-SDK key from the platform.
      **Throws `apikey_in_browser`** in browsers (`window.document` detection) — a naive client integration fails to construct instead of leaking the key. `allowInsecureBrowserUsage: true` downgrades it to `console.error` for e2e only.

      **`X-User-ID`** (`ApiGatewayClient.userId`
      Headless server scenario with a trusted user.id from your backend.
      `console.warn` in browsers without `auth` — a client could spoof somebody else's ID; the backend checks Bearer more strictly.

```ts
// ❌ In the browser — the SDK throws on construction
const billing = new BillingClient({
  paywallId: 'pw_123',
  apiKey: 'sk_live_...' // throws PaywallError('apikey_in_browser')
});

// ✅ In Node — fine
// server.ts (Express handler)
const billing = new BillingClient({
  paywallId: 'pw_123',
  apiKey: process.env.MONETIZE_API_KEY
});
```

For end-to-end server-side patterns (per-user Bearer, storage adapters, webhook handlers, token credit/debit) — see [Headless / server-side](/docs-v2/sdk-v3/headless-server).

## Custom `fetch`

`BillingClient`, `AuthClient`, `ApiGatewayClient` accept `fetch?: typeof fetch` in their options. Convenient for tests / undici / proxies, but unsafe with untrusted code:

  A custom fetch sees `Authorization: Bearer ...` on every request. Never pass a fetch from untrusted packages (npm deps with auto-updates, CDN scripts). If you do use a custom fetch — don't log `init.headers` in production.

## OAuth popup and postMessage

`signInWithOAuth` opens a popup → callback → `postMessage`. The cross-popup attack defence is a PKCE state nonce generated locally and passed via `popup.name = pw-oauth-<state>`. `postMessage` origin is **not** validated (the callback page sends `targetOrigin: '*'` because of COOP restrictions), but the state nonce is unique per popup and unguessable.

**What this protects:**
- A background popup on another page sending you a postMessage with a forged code — it fails the state check.

**What this does NOT protect:**
- XSS on your page — if attacker has JS access they can also listen for postMessage. Covered by general anti-XSS (CSP + sanitize).

## Cross-context auth in extensions

See [auth/session → Cross-context sync](/docs-v2/sdk-v3/auth/session#cross-context-sync-multi-tab--chrome-extension). In short: in a Chrome extension the session is shared across all contexts via `chrome.storage.local`. If the **content script is untrusted** (the user is on a hostile page), Bearer should only live in the background — the content script talks to background via `chrome.runtime.sendMessage` and only the background does fetches with Authorization.

```ts
// content-script.ts (UNTRUSTED — can run on any page)
chrome.runtime.sendMessage({ type: 'gateway.call', providerId, body }, (res) => {
  /* ... */
});

// background.ts (trusted)

const auth = new AuthClient({ paywallId: 'pw_123' });
const billing = new BillingClient({ paywallId: 'pw_123', auth });
const gateway = billing.createApiGatewayClient();

chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
  if (msg.type !== 'gateway.call') return;
  gateway.call(msg).then((r) => r.json()).then(sendResponse);
  return true;
});
```

## Idempotency

To prevent double-clicks / retries over unreliable networks from double-charging or duplicating records:

- `createCheckout({idempotencyKey})` — required in production. The SDK deduplicates parallel clicks by `priceId` automatically, but second-or-two retries — no.
- `signUp({idempotencyKey})` / `signInWithEmail({idempotencyKey})` — protection against double-submit in forms. Treat it as a hint to our façade validation rather than a strict guarantee on the auth backend.
- `gateway.call({...})` — no idempotency yet. A double-click on a CTA in an AI app = two requests = two credits. If this matters, dedupe on the UI side (disable the button until the response).

## Production checklist

- [ ] CSP configured (`script-src` whitelist).
- [ ] `apiKey` NOT in the client bundle (CI grep check).
- [ ] `paywall.destroy()` / `auth.destroy()` called on teardown.
- [ ] `idempotencyKey` passed into `createCheckout` (UUID v4).
- [ ] If threat model is high — considered an in-memory storage adapter.
- [ ] HTTPS everywhere (no HTTP in production).

---

# Storage adapters

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/storage

`StorageAdapter` is the single interface to persistent storage. The SDK writes everything that must survive a reload through it: auth session, bootstrap cache, balances, visitor id, trial counter. By default the SDK picks an implementation that matches the runtime — usually you don't need to configure anything. This page covers when it's worth supplying your own adapter and how to do it right.

## Auto-detection

`createStorage()` without arguments picks by priority:

      Runtime
      Implementation
      Cross-context sync

      Chrome Extension (has `chrome.runtime.id``chrome.storage.local`
      ✅ `chrome.storage.onChanged` — popup ↔ background ↔ content scripts in every tab ↔ options page.

      Browser (has `window.localStorage``window.localStorage`
      ✅ Native `storage` event — multi-tab same-origin.

      Node / Deno / Bun / Edge / tests
      In-memory `Map`
      ❌ Current process only. Reload = logout.

  Detection runs inside every SDK client's constructor. If you want a single adapter across `AuthClient` + `BillingClient`, create it once and pass it explicitly via `opts.storage`.

## Interface

```ts
interface StorageAdapter {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
  /**
   * Optional. Subscription to external changes of `key` (another tab,
   * background context). Returns an unsubscribe function.
   *
   * - `value`: new value or `null` (deleted / absent).
   * - Fires ONLY for cross-context changes; calling `cb` for your own
   *   setItem/removeItem is NOT required.
   */
  watch?(key: string, cb: (value: string | null) => void): () => void;
}
```

Every method is `async`. This is required for `chrome.storage.local` (callback API wrapped in Promise) and for server-side adapters (Redis, KV).

`watch` is optional. Without it, **cross-context sync does not work** — sign-in in one tab won't propagate to another automatically. The memory fallback has no `watch` by design.

## Keys

All keys used by the SDK are exported from `STORAGE_KEYS`:

```ts

```

      Key
      Contents
      Identity-bound

      `pw-visitor-id`
      UUID v4 — stable visitor identifier for analytics. Not PII.
      —

      `pw-{paywallId}-auth-v1`
      `AuthSession` (access_token, refresh_token, expires_at, user). Source of truth for login.
      —

      `pw-{paywallId}-anon-rt-v1`
      Refresh token of the last anonymous user. Survives signOut so the next signInAnonymously picks up the same anon user. Cleared by `signOut({forgetAnonymous: true})` or by a 401 from refresh.
      —

      `pw-{paywallId}-bootstrap-v1`
      Persisted bootstrap (settings/prices/offers/layout/locales/version). 1h TTL.
      —

      `pw-{paywallId}-{identityKey}-user-v1`
      Last-known `PaywallUser` — offline fallback. Key is tied to identity so another user's state doesn't leak after a switch.
      ✅

      `pw-{paywallId}-{identityKey}-balances-v1`
      Persisted balances (AI providers × tokenization queries). 5min TTL.
      ✅

      `pw-{paywallId}-last-login-method`
      `'email' | 'google' | 'apple' | 'github' | 'facebook'` — what the user picked last time. For UI prefill.
      —

      `pw-{paywallId}-last-login-email`
      User's email for form prefill.
      —

      `pw-trial-*`
      Trial counter (firstOpenAt / skipTimes). Shape depends on the paywall's trial mode.
      —

`identityKey` is a stable hash of the current identity (Bearer user.id, email, or anonymousId). On `setIdentity` the key changes — the SDK unsubscribes from the old `watch` and re-subscribes under the new one, so state from the previous identity doesn't leak.

## When to swap the adapter

In most cases — **don't**. Swap when one of these applies:

      Case
      What to supply

      High-security / enterprise — tokens must not survive a reload
      In-memory or sessionStorage

      Server-side / Edge runtime (Node, Cloudflare Workers, Deno Deploy)
      Redis / KV / Durable Object

      At-rest encryption (PII in LocalStorage forbidden by policy)
      Custom adapter with symmetric encryption

## In-memory adapter

The session will not survive a reload — the user will sign in again on every page load. For private/high-security environments this is an intentional trade-off.

```ts

const memoryStorage: StorageAdapter = (() => {
  const m = new Map<string, string>();
  return {
    async getItem(k) { return m.get(k) ?? null; },
    async setItem(k, v) { m.set(k, v); },
    async removeItem(k) { m.delete(k); }
  };
})();

// One shared adapter across both clients — otherwise visitor_id will desync.
const auth = new AuthClient({ paywallId: 'pw_123', apiOrigin: '...', storage: memoryStorage });
const billing = new BillingClient({ paywallId: 'pw_123', apiOrigin: '...', auth, storage: memoryStorage });
```

## sessionStorage adapter

Session lives until the tab is closed; a reload in the same tab survives, a new tab does not.

```ts
const sessionAdapter: StorageAdapter = {
  async getItem(k) { return window.sessionStorage.getItem(k); },
  async setItem(k, v) { window.sessionStorage.setItem(k, v); },
  async removeItem(k) { window.sessionStorage.removeItem(k); }
  // No watch — sessionStorage isn't shared across tabs, so there's nothing to watch.
};
```

  Without `watch`, cross-context sync is off. Multi-tab UX will be broken: sign-in in one tab won't reflect in another. For sessionStorage that's fine (each tab is isolated by design), for custom backend adapters it isn't.

## Encrypted adapter (web)

Symmetric encryption with a key that **itself doesn't live in storage**. Protects against trivial DevTools peeking, but not against XSS (if attacker runs JS, they grab the key too).

```ts
async function encrypt(plaintext: string, key: CryptoKey): Promise<string> {
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const data = new TextEncoder().encode(plaintext);
  const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, data);
  const combined = new Uint8Array(iv.length + ciphertext.byteLength);
  combined.set(iv);
  combined.set(new Uint8Array(ciphertext), iv.length);
  return btoa(String.fromCharCode(...combined));
}

async function decrypt(encrypted: string, key: CryptoKey): Promise<string> {
  const combined = Uint8Array.from(atob(encrypted), (c) => c.charCodeAt(0));
  const iv = combined.slice(0, 12);
  const ciphertext = combined.slice(12);
  const data = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
  return new TextDecoder().decode(data);
}

function makeEncryptedAdapter(key: CryptoKey): StorageAdapter {
  return {
    async getItem(k) {
      const raw = window.localStorage.getItem(k);
      if (!raw) return null;
      try { return await decrypt(raw, key); } catch { return null; }
    },
    async setItem(k, v) {
      window.localStorage.setItem(k, await encrypt(v, key));
    },
    async removeItem(k) {
      window.localStorage.removeItem(k);
    },
    watch(k, cb) {
      const handler = async (e: StorageEvent) => {
        if (e.key !== k || e.storageArea !== window.localStorage) return;
        if (e.newValue == null) return cb(null);
        try { cb(await decrypt(e.newValue, key)); } catch { cb(null); }
      };
      window.addEventListener('storage', handler);
      return () => window.removeEventListener('storage', handler);
    }
  };
}
```

  Encryption adds an async hop on every read/write. With frequent calls (`getAccessToken()` on the hot path) it's measurable. Benchmark before shipping.

## Server-side: Redis / KV

For headless setups (Node/Bun/Edge) where the SDK lives on your backend, you almost always need a per-user adapter — otherwise `pw-{paywallId}-auth-v1` will be shared across every user in the process.

```ts

const redis = new Redis(process.env.REDIS_URL);

function makeUserStorage(userId: string): StorageAdapter {
  const prefix = `monetize:${userId}:`;
  return {
    async getItem(k) {
      return (await redis.get(prefix + k)) ?? null;
    },
    async setItem(k, v) {
      // 30 day TTL — aligned with refresh-token expiry. The SDK updates
      // expires_at in the payload itself; redis TTL guarantees cleanup of
      // orphaned keys.
      await redis.set(prefix + k, v, 'EX', 30 * 24 * 3600);
    },
    async removeItem(k) {
      await redis.del(prefix + k);
    }
    // watch is usually unnecessary on the server — every worker has its own instance.
  };
}

// On a handler call:
const storage = makeUserStorage(req.user.id);
const auth = new AuthClient({ paywallId, apiOrigin, storage });
```

Cloudflare Workers — same idea, via `env.MY_KV.get/put/delete` with a per-user prefix.

  **Persist-per-process vs persist-per-user.** With a long-running worker the Redis adapter is mandatory (otherwise all users would overwrite each other's tokens). For a serverless function (Lambda, edge function) that lives for one request, in-memory is fine — tokens just get re-fetched via refresh on each request.

## Cross-context: `watch` contract

`watch(key, cb)` contract:

- **Fires only on cross-context changes.** Don't call `cb` for your own `setItem` (otherwise you get a loop).
- **`value: string | null`** — `null` means either "deleted" or "never existed".
- **`unsubscribe` is returned synchronously.** No promises.

Native implementations:

```ts
// web/localStorage:
watch(key, cb) {
  const handler = (e: StorageEvent) => {
    if (e.storageArea !== window.localStorage) return;
    if (e.key !== key) return;
    cb(e.newValue); // null when another tab removeItem'd
  };
  window.addEventListener('storage', handler);
  return () => window.removeEventListener('storage', handler);
}
```

```ts
// chrome.storage.local:
watch(key, cb) {
  const handler = (changes, area) => {
    if (area !== 'local') return;
    const ch = changes[key];
    if (!ch) return;
    cb(typeof ch.newValue === 'string' ? ch.newValue : null);
  };
  chrome.storage.onChanged.addListener(handler);
  return () => chrome.storage.onChanged.removeListener(handler);
}
```

## What NOT to do

- **Don't store the session in cookies.** SDK 3.0 is intentionally cookie-free — it works in Chrome extensions, Telegram Mini Apps, and partitioned storage environments. Cookies don't.
- **Don't write your own `lastLoginEmail` over `pw-{paywallId}-last-login-email`.** The SDK will overwrite it.
- **Don't double-prefix keys in your adapter.** The SDK already prefixes with `pw-` and `paywallId`. Double prefixing is a migration bug.
- **Don't add `watch` to an in-memory adapter.** Cross-context sync requires multiple processes; for a single process `watch` is meaningless and only breaks unit tests.

## Utilities

```ts

// Build an adapter with auto-detection (or return what you pass in):
const storage = createStorage(/* override?: StorageAdapter */);

// Resolve visitor_id (reads from storage, generates and saves if missing):
const visitorId = await ensureVisitorId(storage);

// Generate a fresh UUID v4 (for tests):
const id = generateVisitorId();
```

`STORAGE_KEYS` is a typed object of every key the SDK writes. Useful for migrations / debugging:

```ts
console.log(STORAGE_KEYS.authSession('pw_123'));     // 'pw-pw_123-auth-v1'
console.log(STORAGE_KEYS.userState('pw_123', '<identity_hash>'));
```

## Next steps

- [Security](/docs-v2/sdk-v3/security) — why `localStorage` (not `HttpOnly cookies`), threat model, XSS mitigations.
- [Session management](/docs-v2/sdk-v3/auth/session) — `AuthSession`, refresh, cross-context.
- [BillingClient](/docs-v2/sdk-v3/bootstrap) — what gets persisted in bootstrap.

---

# Trial

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/trial

The concept and dashboard configuration of trials are covered in [Paywall → Trial](/docs-v2/paywall/trial). This page describes what SDK 3.0 does when a trial is active. The v2 equivalent (`localStorage` + `visibility_reason`) is in [SDK v2 → Trial](/docs-v2/sdk-v2/client-side/trial).

  **Regular paywalls.** For tokenized paywalls a trial becomes trial tokens on the balance — see [Tokenization](/docs-v2/paywall/tokenization) and [API Gateway](/docs-v2/sdk-v3/api-gateway).

## What happens on `paywall.open()`

`PaywallUI` checks the trial status itself before showing the modal:

1. If **the trial is active** (time hasn't elapsed or the counter hasn't been exhausted) → the modal **does not open**; instead the SDK emits a `trial_blocked` event with the `TrialStatus`. The paywall is "transparent" — the user gets through to the feature.
2. If **the trial has expired** → the modal opens normally. Right before that the SDK emits `trial_expired` exactly once, so the UI can show a "free trial is over" toast.

So you call `paywall.open()` on every paid action — the SDK decides whether to show the modal or not.

## Listening to trial events

```ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});

paywall.on('trial_blocked', (status) => {
  // status — TrialStatus with remaining time / actions info.
  // The modal DID NOT open; your app lets the user into the feature.
  showTrialBanner(status);
});

paywall.on('trial_expired', () => {
  // Fires once at expiry. After that, paywall.open() shows the modal normally.
  trackEvent('trial_expired');
});
```

Full event list and `TrialStatus` shape — in [Events → TrialStatus](/docs-v2/sdk-v3/events#trialstatus).

## Sync access: `paywall.getTrialStatus()`

`paywall.getTrialStatus()` returns the last known `TrialStatus | null` without hitting the network — useful for your own UI ("3 free actions left", "trial expires in 2h"). `null` means: `paywall.open()` / `paywall.getAccess()` has never been called yet, or the trial is disabled in the paywall config.

```ts
const trial = paywall.getTrialStatus();
if (trial?.mode === 'time' && trial.blocked) {
  banner.textContent = `${Math.ceil(trial.remainingMs / 60_000)} min of trial left`;
}
```

To listen for updates — subscribe to `trial_blocked` (it carries the current status) or to `userChange` (when you only want to react to "trial → subscription").

## Side-effect-free check: `paywall.getAccess()`

When you need to decide "can the user use this feature" **without opening the modal** (for a UI gate, not a CTA), use `getAccess()`:

```ts
const access = await paywall.getAccess({});
if (access.granted) {
  runFeature();
} else {
  showUpgradeBanner(access.reason);
}
```

`getAccess()` returns a discriminated union `granted | blocked`. An active trial is returned as `granted` — the single-paywall model says: if the SDK *could* open a modal but a trial blocks it, access is considered granted. That way the UI doesn't burn quota or pop a paywall needlessly.

  **Use the right method for the situation.** `getAccess()` is for feature gates ("can the user run this action?") — it never opens the modal. `paywall.open()` is for the explicit "Buy / Upgrade" CTA — it shows the modal, unless a trial intercepts it.

## Skipping the trial check

There are two situations where you want to bypass the trial and show the modal immediately:

```ts
// 1. "Upgrade now" CTA inside a trial banner — the user chose to buy earlier.
paywall.open({ skipTrial: true });

// 2. Programmatic check without trial leniency (e.g. debugging).
const access = await paywall.getAccess({ skipTrial: true });
```

`skipTrial: true` bypasses the trial window check, but **other visibility checks** (targeting, geo, A/B) still apply — the modal won't open if it was hidden for another reason.

## Reset trial: `paywall.resetTrial()`

Clears the trial counter in storage. Useful for dev mode or admin "replay scenario" buttons. Production hosts rarely call this.

```ts
await paywall.resetTrial();
// The trial_expired flag resets as well; the next open() restarts the trial from zero.
```

## Trial banner with a countdown

```ts
paywall.on('trial_blocked', (status) => {
  const banner = document.getElementById('trial-banner')!;
  banner.hidden = false;

  // Discriminate by status.mode — TS narrows the shape.
  if (status.mode === 'time') {
    const tick = () => {
      const left = (status.expiresAt ?? 0) - Date.now();
      if (left <= 0) {
        clearInterval(timer);
        banner.hidden = true;
        return;
      }
      banner.textContent = `${Math.ceil(left / 60000)} min left`;
    };
    const timer = setInterval(tick, 1000);
    tick();
  } else if (status.mode === 'opens') {
    banner.textContent = `${status.remainingActions} free actions left`;
  }
});

paywall.on('trial_expired', () => {
  document.getElementById('trial-banner')!.hidden = true;
});
```

Exact shapes for `TimeTrialStatus` / `OpensTrialStatus` (`startedAt`, `expiresAt`, `remainingMs`, `totalMs` for `time`; `remainingActions`, `totalActions` for `opens`) — in [Events → TrialStatus](/docs-v2/sdk-v3/events#trialstatus).

## Comparison with v2

| | SDK v2 | SDK v3 |
|---|---|---|
| Storage | `localStorage` / `chrome.storage` | `localStorage` / `chrome.storage` (via `StorageAdapter`) |
| Activation | unconditional `paywall.open()` → throws if expired | `paywall.open()` → emits `trial_blocked` if active, opens modal if expired |
| Read state | `error.visibility_reason` after a failed `open()` | `paywall.getTrialStatus()` (sync) or `paywall.getAccess()` (full gate) |
| Skip trial | no built-in flag | `{ skipTrial: true }` in `open()` / `getAccess()` |
| Expired signal | `error.visibility_reason === 'trial-time' \| 'trial-actions'` | event `trial_expired` |

Behaviour is identical (trial logic on the backend + locally stored counter), API is cleaner.

## See also

- [Concept and dashboard config](/docs-v2/paywall/trial)

- [PaywallUI](/docs-v2/sdk-v3/ui)

- [Events](/docs-v2/sdk-v3/events)

- [SDK v2 equivalent](/docs-v2/sdk-v2/client-side/trial)

---

# PaywallUI

Section: SDK 3.0 (current)
URL: https://monetize.software/docs-v2/sdk-v3/ui

`PaywallUI` is the UI wrapper around `BillingClient` / `AuthClient`. It opens a Shadow DOM modal, handles the auth-gate and checkout flow, emits typed events and exposes a public state machine for the host.

## Opening

```ts

const paywall = new PaywallUI({ paywallId: 'pw_123', auth: true });

document.getElementById('upgrade').onclick = () => paywall.open();
document.getElementById('login').onclick = () => paywall.openSignin();
document.getElementById('register').onclick = () => paywall.openSignup();
document.getElementById('help').onclick = () => paywall.openSupport();
```

      Method
      What it does

      `open(opts?)`
      Opens the modal with the layout (prices + auth_panel/current_session per paywall config). `opts: OpenOptions` — `identity`, `skipTrial`, `skipVisibility`, `renew`.

      `openAuth(opts?)`
      Opens only the auth-gate (signin form). Alias for `openSignin()` — kept for backwards compatibility.

      `openSignin(opts?)`
      Opens the auth-gate on the signin form. Equivalent to `openAuth()`, just a more explicit name.

      `openSignup(opts?)`
      Opens the auth-gate in signup mode (email/password/repeat). If the admin disabled `allow_signup` in the layout — falls back to signin.

      `signInAnonymously()`
      Headless `signInAnonymously` without opening the modal. Returns `Promise<AuthSession>`. Idempotent (already anonymous → instant return) → resumes the same `user_id` via `anonRefreshToken` in storage → fresh `/auth/anonymous/signin`. After `signOut()` (without `forgetAnonymous`) a repeat call returns the **same anonymous user** — balance/trial preserved. Parallel calls deduplicate.

      `openSupport(opts?)`
      Opens only the support form. Back closes.

      `checkout(priceId, opts?)`
      Direct checkout for a specific price — skips the plan-picker layout and goes straight to `/start-checkout`. Reuses the preauth-gate, popup-blocked and awaiting-payment screens. Already-paid is a headless reject: emits `purchase_completed { restored: true }` without showing the "Subscription restored" view. See [direct checkout](#checkoutpriceid-opts) below.

      `close()`
      Closes the modal. Emits `close`.

      `preload({signal?})`
      Warms up bootstrap + balances in the background. Best-effort — never throws.

      `destroy()`
      Full teardown: unmounts the modal, clears listeners, releases managed-auth.

      `getAccess(opts?)`
      Side-effect-free check "should I gate this feature?". Returns discriminated `granted` / `blocked`. See [Trial → getAccess](/docs-v2/sdk-v3/trial#side-effect-free-check-paywallgetaccess).

      `getState()` / `onStateChange(cb, opts?)`
      State machine snapshot + subscription. See below.

      `getTrialStatus()`
      Last known `TrialStatus | null` (sync, no network). `null` — `open()` / `getAccess()` not called yet, or trial disabled.

      `getVisibility()`
      Last server-computed `VisibilityStatus | null` (sync). Useful for rendering a "service unavailable in your country" fallback without opening the modal.

      `resetTrial()`
      Clears trial state in storage. For dev mode / admin "replay scenario" buttons. In production hosts rarely call this.

      `getPrices(opts?)` / `getCachedPrices()`
      Shortcuts over `billing.getPrices()` for rendering pricing cards outside the modal. See [BillingClient → getPrices](/docs-v2/sdk-v3/bootstrap#getpricesopts--getcachedprices).

      `getUserLanguage()`
      Snapshot of the user's resolved language for syncing your i18n with what the paywall shows. See [Locale & language](/docs-v2/sdk-v3/locale).

      `checkReturn()`
      Scans the current URL for `?paywall_status=paid|failed|cancelled` markers and emits `purchase_completed` / `purchase_failed`. The constructor runs this in a microtask when `autoDetectReturn: true` (default).

      `on(event, cb)` / `off(event, cb)`
      Typed event subscription. See [Events](/docs-v2/sdk-v3/events).

      `onUserChange(cb)`
      Shortcut for `paywall.on('userChange', cb)` — the most common subscription.

## `checkout(priceId, opts?)`

Direct checkout: get a hosted checkout URL for a specific price and open it in a new tab, **without** showing the plan list. Useful when the host renders its own pricing cards / table and the click on "Buy" should land in Stripe / Paddle / Chargebee / Freemius / Overpay directly.

```ts

const paywall = new PaywallUI({ paywallId: 'pw_123', auth: true });

document.querySelectorAll<HTMLButtonElement>('[data-price-id]').forEach((el) => {
  el.addEventListener('click', () => {
    paywall.checkout(el.dataset.priceId!);
  });
});

paywall.on('purchase_completed', (p) => {
  if (p.restored) showToast('You already have an active subscription.');
  else unlockPremium();
});
```

### Late-mount UX

Unlike `open()`, **no modal appears while the SDK is preparing** the checkout. Bootstrap, visibility / trial gates, the active-subscription pre-check and `createCheckout` all run headless — there's no loading-flash modal in front of the user. The host's button is the only "I'm working" surface during these 200–500 ms.

Subscribe to [`state.processing`](#state-machine) (or use `<PaywallButton priceId>` in [React](/docs-v2/sdk-v3/react/components#paywallbutton)) and show a spinner directly on your CTA:

```ts
paywall.onStateChange((state) => {
  myButton.disabled = state.processing;
  myButton.classList.toggle('busy', state.processing);
});
```

The modal is mounted **only when actual UI is needed**:

- `checkout_mode: 'preauth'` + managed-auth + no real session → auth-gate (signin form). After success the modal auto-resumes into `createCheckout()` with the same `priceId`.
- Popup blocked by the browser (lost transient activation after async signin, aggressive mobile blockers) → `popup_blocked` view with a retry button under a fresh user gesture.
- Popup opened successfully → `awaiting_payment` view with "I've paid" verify, "Open checkout again" and "Tab closed? Try again".

### Headless-reject paths (no modal)

- **Already-paid.** When the user already has an active subscription — detected via cached user, fresh bootstrap, the preauth signin, or a `409 hasActivePurchase` from the backend — the SDK emits `purchase_completed { restored: true }` and **does not show** a "Subscription restored" view. The host surfaces it however it likes (toast, redirect, badge update via `userChange`).
- **Gate blocked.** `visibility_blocked` / `trial_blocked` fire just like in `open()`. No modal.
- **Errors.** `error` fires (`identity.email` missing, bootstrap failure, `createCheckout` rejection). No modal.

The plan-picker layout **never appears in direct-checkout flow**, not even as an error fallback — the host already owns plan selection.

### Offers applied automatically

`checkout(priceId)` resolves the active offer for the price through `getOfferForPrice(priceId)` and threads its `offerId` into `/start-checkout`. This is required for **duration-offers** (countdown stored in `clientStorage` — the backend can't validate the timer, so without an explicit `offerId` the discount would silently not apply on the hosted checkout, even though the UI showed it). End-date offers go through too; the backend re-verifies applicability against country/email/mode.

### Requirements

- **`identity.email` must be set** before the call — via `paywall.checkout(priceId, { identity })`, an earlier `paywall.open({ identity })`, `setIdentity()`, or managed-auth. Without an email the backend rejects `/start-checkout` with `400`; the SDK emits `error`.
- In `checkout_mode: 'preauth'` without managed-auth, the host is responsible for collecting the email before the call — the SDK has nowhere to show a signin form.

### Fully headless (no modal at all)

If the host wants only the checkout URL (e.g. renders a custom in-page "awaiting payment" screen instead of the SDK's), bypass the modal entirely:

```ts

const offer = findApplicableOffer(paywall.billing.getCachedOffers(), '42');
const result = await paywall.billing.createCheckout({
  priceId: '42',
  offerId: offer?.id  // required for duration-offers
});
window.open(result.url, '_blank');
```

In that path the host owns auth-gate UX, popup-blocked retry, the awaiting-payment screen, and `purchase_completed` wiring (via `paywall.on('purchase_completed', …)` or `checkReturn()` on the success page). For most apps `paywall.checkout()` is the better trade-off — same control over the storefront, fewer screens to build.

## State machine

`PaywallUI` keeps a public snapshot of the modal's state. Useful for:

- **`useSyncExternalStore` in React** — single source of truth instead of stitching a dozen `on()` listeners;
- **Funnel analytics** — track every transition (closed → loading → ready → ...);
- **Conditional UI** — the host renders its own Upgrade button based on `state.view`.

```ts
type PaywallStateSnapshot = {
  open: boolean;          // modal is visible
  view:                   // what's shown (null when closed)
    | 'loading'
    | 'error'
    | 'layout'
    | 'auth'
    | 'support'
    | 'awaiting_payment'  // checkout opened in a new tab
    | 'popup_blocked'     // browser blocked the popup
    | 'purchased'         // success view with Continue
    | null;
  error: PaywallError | null;
  /** Direct-checkout (`paywall.checkout(priceId)`) is doing background work —
   *  bootstrap + visibility/trial gates + createCheckout — before any UI is
   *  needed. Host's CTA button should show busy/disabled while true so the
   *  user gets feedback without a modal-flash. Always false during the
   *  `paywall.open()` flow (the modal mounts immediately with its own
   *  LoadingView). */
  processing: boolean;
};
```

### Using with React

```tsx

function PaywallStatus() {
  const state = useSyncExternalStore(
    (cb) => paywall.onStateChange(cb, { immediate: 'none' }),
    () => paywall.getState(),
    () => paywall.getState() // SSR fallback (closed state)
  );

  if (state.view === 'loading') return <Spinner />;
  if (state.view === 'error') return <ErrorBox err={state.error!} />;
  if (state.view === 'awaiting_payment') return <p>Paying in new tab…</p>;
  return null;
}
```

`useSyncExternalStore` calls `getState()` itself after `subscribe` — no initial snapshot needed via the listener, hence `immediate: 'none'`.

### Manual usage (Vue / Svelte / vanilla)

```ts
const off = paywall.onStateChange(
  (state) => {
    if (state.view === 'purchased') confetti();
    if (state.view === 'error') showToast(state.error!.message);
  },
  { immediate: 'sync' } // get current snapshot synchronously
);
// off() to unsubscribe
```

### The `immediate` option

      Value
      When

      `'microtask'` (default)
      Initial snapshot via `queueMicrotask`. Safe for most integrations — the host gets to reset state in the same tick.

      `'sync'`
      Initial snapshot right now. Handy for Vue/Svelte/vanilla when you need an immediate read.

      `'none'`
      Skip initial — only real changes. For `useSyncExternalStore` (it reads the snapshot itself).

  Snapshot objects are stable: while state hasn't changed, repeated `getState()` returns the same `===`-equal object. Important for `useSyncExternalStore` — otherwise React would re-render on every tick.

## Events vs state

Both events and state expose what's happening — the choice depends on the task.

      Scenario
      Event
      State

      "User successfully purchased" (one-shot side-effect: confetti, redirect, slack ping)
      ✅ `purchase_completed`
      `state.view='purchased'` is sticky — on re-open you may retrigger

      "Is the modal open right now?"
      Have to stitch `open`+`close`
      ✅ `state.open`

      React component rendering a loader
      Hard (multiple events, race)
      ✅ `useSyncExternalStore`

      Conversion funnel analytics
      ✅ Clean stream: open → ready → price_selected → checkout_started → purchase_completed
      State is coarser — not every event maps to a transition

Rule of thumb: **events for side-effects, state for rendering**.

## Constructor options (`PaywallUIOptions````ts
interface PaywallUIOptions extends Omit<BillingClientOptions, 'auth'> {
  paywallId: string;
  apiOrigin: string;
  identity?: Identity;
  storage?: StorageAdapter;
  capabilities?: string[];
  fetch?: typeof fetch;
  apiKey?: string;
  client?: BillingClient;
  host?: HTMLElement;
  /** Wire managed-auth. true (creates AuthClient), AuthClient (use existing),
   *  or Partial<AuthClientOptions> (custom options). */
  auth?: true | AuthClient | Partial<AuthClientOptions>;
  /** Auto-scan URL for ?paywall_status= markers on construction. Default: true. */
  autoDetectReturn?: boolean;
  /** Shadow DOM mode. Default 'closed' (full isolation). 'open' — for Playwright
   *  e2e and live admin preview. */
  shadowMode?: 'open' | 'closed';
  /** Analytics. false to disable, object for custom batch settings or endpoint. */
  analytics?: boolean | AnalyticsOptions;
  /** When bootstrap isn't cached: render the modal **immediately** with a
   *  spinner and run gates after data arrives (`true`, default), or **wait**
   *  for bootstrap before mounting (`false`). */
  mountThenLoad?: boolean;
}
```

Auth resolution:

- `auth: true` — SDK creates a new `AuthClient` with the same `paywallId/apiOrigin/storage` as BillingClient.
- `auth: AuthClient` — host supplies an existing instance (useful for multi-paywall apps or pre-construction signin).
- `auth: Partial<AuthClientOptions>` — `paywallId` is filled in, the rest comes from your overrides.
- Omitted — hybrid mode: identity is passed via `opts.identity` or `paywall.open({ identity })`.

## Lifecycle hooks for hosts

```ts
// On host unmount (SPA route change, hot reload, tests):
paywall.destroy();
```

`destroy()` is idempotent and safe to call multiple times. It unmounts the Shadow DOM modal, removes every event listener, releases the managed `AuthClient` (only if `auth: true` was used — externally provided `AuthClient` lifecycle stays with the host), and stops the analytics flush timer.

---

# Custom Domains Overview

Section: Custom Domains
URL: https://monetize.software/docs-v2/custom-domains/overview

  This feature only relevant when paywall is in client mode.

Custom domains allow you to use your own domain for displaying paywalls instead of the standard `appbox.space`. This makes the payment process more trustworthy for your users and improves branding.

## What are custom domains?

A custom domain is a subdomain of your website (e.g., `app.yoursite.com` or `api.yoursite.com`) that will be used to display the paywall. Instead of users seeing `appbox.space` in the address bar, they will see your domain.

  **Important:** The checkout page itself will open on the domain specified in
  your payment processor settings and is not related to the custom domain. The
  custom domain only affects the paywall display and authentication process, not
  the actual payment process.

## Benefits of using custom domains

### 🔒 Solving third-party cookie blocking issues

**Main problem:** Many browsers block third-party cookies by default. When a paywall loads from the `appbox.space` domain while your site is on a different domain, the browser may block authentication cookies, leading to user login issues.

  This issue is **only relevant for SaaS applications and websites**. If you're
  building a **browser extension**, this problem doesn't apply to you since
  extensions use Chrome's built-in storage for authentication instead of
  cookies.

**Solution:** Using a custom domain (subdomain of your main site) bypasses these restrictions, as browsers consider subdomains part of the same domain.

### 🎨 Improved branding

- Users see your domain in the address bar
- Increases trust in the payment process
- Creates a consistent user experience

### 🚀 Higher conversion rates

- Users are more likely to complete payment when seeing a familiar domain
- Reduces abandonment due to distrust of third-party domains
- Improves overall perception of your service

## Technical requirements

### Supported domain types

✅ **Supported:** Third-level subdomains

- `app.yoursite.com`
- `platform.yoursite.com`
- `account.yoursite.com`
- `api.yoursite.com`

❌ **Not supported:** Root domains

- `yoursite.com`
- `www.yoursite.com`

  **Avoid payment-related names** like `pay.*`, `paywall.*`, `checkout.*`, `billing.*`. These keywords are often blocked by adblockers (uBlock, AdBlock Plus, Brave Shields), which will break the paywall for a notable share of your users. Prefer neutral subdomains like `app.*`, `platform.*`, `account.*`.

### DNS configuration

To make a custom domain work, delegate your subdomain to DigitalOcean by creating NS records for the subdomain in your primary DNS provider. Example for `app.yoursite.com`:

```
NS app.yoursite.com ns1.digitalocean.com
NS app.yoursite.com ns2.digitalocean.com
NS app.yoursite.com ns3.digitalocean.com
```

This is called subdomain delegation. You do NOT need to change nameservers for the entire root domain — only delegate the specific subdomain (e.g., `app`).

## Setup process

1. **Add domain** — add the subdomain in settings
2. **Delegate via NS** — create NS records for your subdomain pointing to DigitalOcean (ns1-3)
3. **Verification** — we check NS records; if valid, the domain gets the status **"Waiting for moderation"**
4. **Moderation** — moderator sets the domain to **"Verified"**
5. **Link to paywall** — select the verified domain for a specific paywall and get the updated installation script

## Security

- Automatic NS record validation to prevent misconfiguration
- Moderation step to protect against unauthorized domain usage

## Limitations

- Maximum DNS propagation time: up to 48 hours
- Only third-level subdomains are supported
- Your DNS provider must support subdomain delegation via NS records

---

Ready to start? Go to [creating a custom domain](/docs-v2/custom-domains/create-domain).

---

# Webhooks Overview

Section: Webhooks
URL: https://monetize.software/docs-v2/webhooks/overview

Monetize.software can send you notifications any time an event happens in your app and monitor state changes for your subscribers.

## Benefits

With webhooks integrated, you can:

- **Keep your backend synchronized** with real-time subscription and purchase data
- **Set up automated workflows** that respond to subscription events
- **Send timely communications** to subscribers about billing issues or engage with them during unsubscription

## Supported Events

| Event                    | Description                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| `payment.completed`      | Successfully completed payment (one-time or first subscription payment) |
| `subscription.created`   | New subscription creation                                               |
| `subscription.updated`   | Subscription update (plan change, status change, etc.)                  |
| `subscription.cancelled` | Subscription cancellation                                               |
| `refund.created`         | Refund creation                                                         |

## Webhook Structure

### HTTP Headers

Every webhook request includes these headers:

```http
Content-Type: application/json
User-Agent: Monetize-Webhooks/1.0
X-Monetize-Signature: sha256=<signature>
```

  **Signature Header:** The `X-Monetize-Signature` header is only included if you have configured a secret key for webhook verification.

### Payload Structure

Each webhook notification has this JSON structure:

```json
{
  "id": "evt_1234567890_abcdef123",
  "type": "payment.completed",
  "created_at": "2024-01-15T12:30:45.000Z",
  "data": {
    "price": {
      "id": "cus_customer123",
      "unit_amount": 2000,
      "interval": "year"
    },
    "customer": {
      "id": "cus_customer123",
      "email": "user@example.com"
    },
    "user": {
      "id": "cus_customer123",
      "metadata": {
        "some-custom-field": "value"
      }
    },
    "paywall": {
      "id": "123"
    },
    "acquiring": {
      "id": "acq_456",
      "provider": "stripe"
    }
  }
}
```

### Common Fields

| Field        | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| `id`         | string | Unique event identifier                    |
| `type`       | string | Event type (e.g., "payment.completed")     |
| `created_at` | string | Event creation time in ISO 8601 format     |
| `data`       | object | Event-specific data containing information |

## Event-Specific Fields

### Payment Events

Additional fields for payment events:

```json
"payment": {
  "id": "pi_payment123",
  "status": "succeeded"
}
```

### Subscription Events

Additional fields for subscription events:

```json
"subscription": {
  "id": "sub_subscription123",
  "status": "active",
  "current_period_start": "2024-01-15T12:30:45.000Z",
  "current_period_end": "2024-02-15T12:30:45.000Z"
}
```

### Refund Events

Additional fields for refund events:

```json
"refund": {
  "id": "re_refund123",
  "reason": "requested_by_customer",
  "amount": 2999
}
```

## Authentication Verification

### Webhook Signature

If you have configured a secret key, each webhook will contain an `X-Monetize-Signature` header with an HMAC SHA256 signature of the request body.

  **Security:** Always verify webhook signatures in production to ensure the request is genuinely from Monetize.software.

### Signature Verification Examples

    ```javascript
    const crypto = require('crypto');

    function verifyWebhookSignature(payload, signature, secret) {
      const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

      // Remove "sha256=" prefix from header
      signature = signature.replace('sha256=', '');

      return crypto.timingSafeEqual(
        Buffer.from(expectedSignature),
        Buffer.from(signature)
      );
    }

    // Usage
    const isValid = verifyWebhookSignature(
      req.body,
      req.headers['x-monetize-signature'],
      'your_webhook_secret'
    );
    ```

    ```python
    import hmac
    import hashlib

    def verify_webhook_signature(payload, signature, secret):
        expected_signature = hmac.new(
            secret.encode('utf-8'),
            payload.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()

        # Remove "sha256=" prefix from header
        signature = signature.replace('sha256=', '')

        return hmac.compare_digest(expected_signature, signature)

    # Usage
    is_valid = verify_webhook_signature(
        request.body,
        request.headers.get('X-Monetize-Signature'),
        'your_webhook_secret'
    )
    ```

    ```php
    function verifyWebhookSignature($payload, $signature, $secret) {
        $expectedSignature = hash_hmac('sha256', $payload, $secret);

        // Remove "sha256=" prefix from header
        $signature = str_replace('sha256=', '', $signature);

        return hash_equals($expectedSignature, $signature);
    }

    // Usage
    $isValid = verifyWebhookSignature(
        file_get_contents('php://input'),
        $_SERVER['HTTP_X_MONETIZE_SIGNATURE'],
        'your_webhook_secret'
    );
    ```

## Webhook Processing

### Endpoint Requirements

- **HTTPS:** Webhooks are only sent to HTTPS URLs
- **Response Status:** Your endpoint should return HTTP status 200-299 for successful processing
- **Timeout:** Response timeout is 10 seconds
- **Idempotency:** Be prepared to receive duplicate events

### Processing Example

```javascript
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/monetize', async (req, res) => {
  try {
    // Verify signature
    const signature = req.headers['x-monetize-signature'];
    if (signature && !verifyWebhookSignature(
      JSON.stringify(req.body),
      signature,
      'your_secret'
    )) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // Parse event
    const event = req.body;

    // Process event based on type
    switch (event.type) {
      case 'payment.completed':
        await handlePaymentCompleted(event.data);
        break;
      case 'subscription.created':
        await handleSubscriptionCreated(event.data);
        break;
      case 'subscription.updated':
        await handleSubscriptionUpdated(event.data);
        break;
      case 'subscription.cancelled':
        await handleSubscriptionCancelled(event.data);
        break;
      case 'refund.created':
        await handleRefundCreated(event.data);
        break;
      default:
        console.log(`Unhandled event type: ${event.type}`);
    }

    res.status(200).json({ status: 'success' });

  } catch (err) {
    console.error(`Webhook error: ${err}`);
    res.status(500).json({ error: 'Internal error' });
  }
});

async function handlePaymentCompleted(data) {
  console.log(`Payment completed: ${data.payment.id}`);
  // Example: Activate user access
  await activateUserAccess(data.user.id);
}

async function handleSubscriptionCreated(data) {
  console.log(`Subscription created: ${data.subscription.id}`);
  // Example: Grant premium features access
  await grantPremiumAccess(data.user.id);
}
```

## Retry Mechanism

The system automatically retries webhook delivery on failure:

- **Number of attempts:** 5 attempts
- **Intervals:** 5, 10, 20, 40, and 80 minutes
- **Retry conditions:** HTTP status 5xx or connection timeout

## Logging

All webhook delivery attempts are logged, including:

- **Send time** - When the webhook was sent
- **HTTP response status** - Response code from your endpoint
- **Response body** - First 1000 characters of response
- **Error messages** - Any error details
- **Attempt count** - Which attempt number this was

  **Access Logs:** Logs are available in the control panel under Settings → Webhooks → select specific webhook.

## Security

  **Security Best Practices:** Follow these guidelines to ensure secure webhook processing.

### Security Guidelines

1. **Always verify the signature** when using a secret key
2. **Use HTTPS** for all webhook URLs
3. **Don't log full webhook data** in plain text
4. **Restrict access** to webhook endpoints
5. **Validate data** before processing

## Limitations

| Limitation                   | Value      |
| ---------------------------- | ---------- |
| Maximum payload size         | 1 MB       |
| Timeout                      | 10 seconds |
| Maximum webhooks per account | 10         |
| Log retention                | 30 days    |

## Support

If you encounter webhook issues, contact technical support providing:

- **Webhook ID** - Identifier of the problematic webhook
- **Event time** - When the issue occurred
- **Expected behavior** - What should have happened
- **Actual behavior** - What actually happened
- **Your side logs** - Any relevant logs from your endpoint

## Next Steps

- [Create Webhook](/docs-v2/webhooks/create-webhook)

- [Webhook Events and Scenarios](/docs-v2/webhooks/events)

---

# Webhook Events and Scenarios

Section: Webhooks
URL: https://monetize.software/docs-v2/webhooks/events

Learn about different webhook events and their usage scenarios to properly handle subscription and payment workflows.

## Event Types

### 1. payment.completed

**Description:** Completion of a one-time payment (lifetime)

**When sent:** When a one-time product or service payment is successful

**Use cases:**

- Lifetime access purchases
- One-time product purchases
- Single service payments

### 2. subscription.created

**Description:** Creation of a new subscription

**When sent:** When a user creates a subscription for the first time

**Use cases:**

- New subscription activation
- Trial period start
- Initial subscription setup

### 3. subscription.updated

**Description:** Update of an existing subscription

**When sent:** When subscription status, plan, or other parameters change

**Use cases:**

- Plan upgrades/downgrades
- Subscription renewals
- Status changes
- Reactivation

  **Paddle Note:** Paddle may sometimes send multiple consecutive `subscription.updated` webhooks for the same subscription, even if business data (status, product, price) hasn't changed. This is normal platform behavior and doesn't require special handling.

### 4. subscription.cancelled

**Description:** Subscription cancellation

**When sent:** When a subscription is cancelled by user or system

**Use cases:**

- User cancellation
- Failed payment cancellation
- Administrative cancellation

### 5. refund.created

**Description:** Creation of a refund

**When sent:** When a payment refund is processed

**Use cases:**

- Customer refund requests
- Administrative refunds
- Dispute resolutions

## Subscription Object Fields

The `data.subscription` object in `subscription.*` events contains the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Subscription identifier |
| `status` | string | One of `active`, `trialing`, `past_due`, `canceled`, `incomplete` |
| `current_period_start` | string (ISO) | Start of the current billing period |
| `current_period_end` | string (ISO) | Next billing date. **Not rewound on immediate cancellation** — use `ended_at` for the actual end of access |
| `trial_period_start` | string (ISO) | Start of trial, if any |
| `trial_period_end` | string (ISO) | End of trial, if any |
| `cancel_at_period_end` | boolean | `true` when cancellation is scheduled for the end of the current period |
| `cancel_at` | string (ISO) | When the subscription will be cancelled (set together with `cancel_at_period_end: true`) |
| `canceled_at` | string (ISO) | When the user requested cancellation |
| `ended_at` | string (ISO) | When the subscription actually ended. Set on immediate cancellation and after `cancel_at` is reached |

  To determine whether a subscription is currently active, check `status` and `ended_at`. If `ended_at` is set and not in the future, access should be revoked even if `current_period_end` is later. If `cancel_at_period_end` is `true`, the subscription is active but will not renew.

## Event Scenarios

### Scenario 1: Lifetime Access Purchase

| Step | Event               | Description                                |
| ---- | ------------------- | ------------------------------------------ |
| 1    | User makes payment  | User completes payment for lifetime access |
| 2    | `payment.completed` | Payment successfully processed             |

### Payment Successful

```json
{
  "type": "payment.completed",
  "data": {
    "payment": {
      "id": "pi_lifetime123",
      "status": "succeeded"
    },
    "price": {
      "interval": "lifetime"
    }
  }
}
```

Event: **payment.completed** - payment successfully completed

**In case of refund:**

### Refund Processed

```json
{
  "type": "refund.created",
  "data": {
    "refund": {
      "id": "re_refund123",
      "reason": "requested_by_customer",
      "amount": 9999
    }
  }
}
```

Event: **refund.created** - refund processed

### Scenario 2: Subscription Without Trial

| Step | Event                  | Description                             |
| ---- | ---------------------- | --------------------------------------- |
| 1    | User subscribes        | User completes payment for subscription |
| 2    | `subscription.created` | Subscription created and activated      |

### Subscription Created

```json
{
  "type": "subscription.created",
  "data": {
    "subscription": {
      "id": "sub_active123",
      "status": "active",
      "current_period_start": "2024-01-15T12:30:45.000Z",
      "current_period_end": "2024-02-15T12:30:45.000Z"
    }
  }
}
```

Event: **subscription.created** - subscription created and activated

**On subscription renewal:**

### Subscription Renewed

```json
{
  "type": "subscription.updated",
  "data": {
    "subscription": {
      "id": "sub_active123",
      "status": "active",
      "current_period_start": "2024-02-15T12:30:45.000Z",
      "current_period_end": "2024-03-15T12:30:45.000Z"
    }
  }
}
```

Event: **subscription.updated** - subscription automatically renewed

Updated `subscription.current_period_start` and `subscription.current_period_end` will be sent for the current subscription

**On subscription cancellation:**

    **Variant A:** Cancellation at period end

    | Step | Event | Description |
    |------|-------|-------------|
    | 1 | User cancels | User requests cancellation |
    | 2 | `subscription.updated` | Subscription scheduled for cancellation, remains active |
    | 3 | End of period | Period reaches `cancel_at` |
    | 4 | `subscription.cancelled` | Subscription actually cancelled |

    First, when the user requests cancellation:

    ```json
    {
      "type": "subscription.updated",
      "data": {
        "subscription": {
          "id": "sub_active123",
          "status": "active",
          "cancel_at_period_end": true,
          "cancel_at": "2025-02-15T12:30:45.000Z",
          "canceled_at": "2024-02-15T12:30:45.000Z",
          "current_period_end": "2025-02-15T12:30:45.000Z"
        }
      }
    }
    ```

    Then, when the period ends:

    ```json
    {
      "type": "subscription.cancelled",
      "data": {
        "subscription": {
          "id": "sub_active123",
          "status": "canceled",
          "cancel_at_period_end": true,
          "canceled_at": "2024-02-15T12:30:45.000Z",
          "ended_at": "2025-02-15T12:30:45.000Z"
        }
      }
    }
    ```

      Subscription remains in `active` status with `cancel_at_period_end: true` until `cancel_at` is reached, then status changes to `canceled` and `ended_at` is set.

    **Variant B:** Immediate cancellation

    | Step | Event | Description |
    |------|-------|-------------|
    | 1 | User cancels | User requests immediate cancellation |
    | 2 | `subscription.cancelled` | Subscription immediately cancelled |

    ```json
    {
      "type": "subscription.cancelled",
      "data": {
        "subscription": {
          "id": "sub_active123",
          "status": "canceled",
          "cancel_at_period_end": false,
          "canceled_at": "2024-01-20T12:30:45.000Z",
          "ended_at": "2024-01-20T12:30:45.000Z",
          "current_period_end": "2025-01-20T12:30:45.000Z"
        }
      }
    }
    ```

    Event: **subscription.cancelled** - subscription immediately cancelled

      For immediate cancellation, `current_period_end` keeps the original next-billing date (it is not rewound). Use `ended_at` as the actual end of access. If `ended_at` is set and not in the future, the subscription is closed regardless of `current_period_end`.

### Scenario 3: Subscription With Trial Period

| Step | Event                  | Description                                |
| ---- | ---------------------- | ------------------------------------------ |
| 1    | User starts trial      | User begins trial period                   |
| 2    | `subscription.created` | Subscription created with status: trialing |
| 3    | Trial period ends      | Trial period expires                       |
| 4    | `subscription.updated` | Subscription updated with status: active   |

### Trial Started

```json
{
  "type": "subscription.created",
  "data": {
    "subscription": {
      "id": "sub_trial123",
      "status": "trialing",
      "trial_period_start": "2024-01-15T12:30:45.000Z",
      "trial_period_end": "2024-01-22T12:30:45.000Z"
    }
  }
}
```

Event: **subscription.created** - subscription created with status "trialing"

Fields `subscription.trial_period_start` and `subscription.trial_period_end` will also be provided

### Trial Ended

```json
{
  "type": "subscription.updated",
  "data": {
    "subscription": {
      "id": "sub_trial123",
      "status": "active",
      "current_period_start": "2024-01-22T12:30:45.000Z",
      "current_period_end": "2024-02-22T12:30:45.000Z"
    }
  }
}
```

Event: **subscription.updated** - trial period ended, subscription became active

Updated `subscription.current_period_start` and `subscription.current_period_end` will be sent for the current subscription

**If user cancels during trial:**

### Trial Cancelled

```json
{
  "type": "subscription.cancelled",
  "data": {
    "subscription": {
      "id": "sub_trial123",
      "status": "canceled",
      "canceled_at": "2024-01-18T12:30:45.000Z",
      "ended_at": "2024-01-18T12:30:45.000Z"
    }
  }
}
```

Event: **subscription.cancelled** - subscription cancelled during trial period

### Scenario 4: Plan Change (Upgrade/Downgrade)

| Step | Event                  | Description                                   |
| ---- | ---------------------- | --------------------------------------------- |
| 1    | User changes plan      | User upgrades or downgrades subscription plan |
| 2    | `subscription.updated` | Subscription updated with new plan            |

### Plan Changed

```json
{
  "type": "subscription.updated",
  "data": {
    "subscription": {
      "id": "sub_active123",
      "status": "active"
    },
    "price": {
      "id": "price_new_plan",
      "unit_amount": 4999,
      "interval": "month"
    }
  }
}
```

Event: **subscription.updated** - subscription plan changed

**Possible changes leading to subscription.updated:**

- Plan change (upgrade/downgrade)
- Subscription renewal
- Reactivation of cancelled subscription

### Scenario 5: Subscription Refund

| Step | Event                    | Description                          |
| ---- | ------------------------ | ------------------------------------ |
| 1    | Refund requested         | Active subscription refund requested |
| 2    | `refund.created`         | Refund processed                     |
| 3    | `subscription.cancelled` | Subscription cancelled due to refund |

### Refund Created

```json
{
  "type": "refund.created",
  "data": {
    "refund": {
      "id": "re_sub_refund456",
      "reason": "requested_by_customer",
      "amount": 2999
    }
  }
}
```

Event: **refund.created** - refund processed

### Subscription Cancelled

```json
{
  "type": "subscription.cancelled",
  "data": {
    "subscription": {
      "id": "sub_active123",
      "status": "canceled",
      "canceled_at": "2024-01-20T12:30:45.000Z",
      "ended_at": "2024-01-20T12:30:45.000Z"
    }
  }
}
```

Event: **subscription.cancelled** - subscription cancelled due to refund

## Event Handling Examples

### Complete Event Handler

```javascript
const handleWebhookEvent = async (event) => {
  const { type, data } = event;

  switch (type) {
    case 'payment.completed':
      await handlePaymentCompleted(data);
      break;

    case 'subscription.created':
      await handleSubscriptionCreated(data);
      break;

    case 'subscription.updated':
      await handleSubscriptionUpdated(data);
      break;

    case 'subscription.cancelled':
      await handleSubscriptionCancelled(data);
      break;

    case 'refund.created':
      await handleRefundCreated(data);
      break;

    default:
      console.log(`Unhandled event type: ${type}`);
  }
};

// Handler implementations
const handlePaymentCompleted = async (data) => {
  const { payment, price, user, customer } = data;

  if (price.interval === 'lifetime') {
    // Grant lifetime access
    await grantLifetimeAccess(user.id);
    console.log(`Lifetime access granted to user ${user.id}`);
  } else {
    // Handle one-time payment
    await processOneTimePayment(payment.id, user.id);
  }

  // Send confirmation email
  await sendPaymentConfirmation(customer.email, price.unit_amount);
};

const handleSubscriptionCreated = async (data) => {
  const { subscription, user, customer } = data;

  if (subscription.status === 'trialing') {
    // Start trial period
    await startTrialPeriod(user.id, subscription.trial_period_end);
    console.log(`Trial started for user ${user.id}`);
  } else if (subscription.status === 'active') {
    // Activate subscription immediately
    await activateSubscription(user.id, subscription.id);
    console.log(`Subscription activated for user ${user.id}`);
  }

  // Send welcome email
  await sendWelcomeEmail(customer.email, subscription.status);
};
```

## Best Practices

### 1. Handle Event Order

  **Event Order:** Events may not always arrive in chronological order. Always check timestamps and handle out-of-order events.

```javascript
const handleEventWithOrder = async (event) => {
  const lastProcessedTime = await getLastProcessedTime(event.data.user.id);

  if (new Date(event.created_at) < lastProcessedTime) {
    console.log('Out of order event, handling carefully...');
    // Handle out-of-order event logic
  }

  await processEvent(event);
  await updateLastProcessedTime(event.data.user.id, event.created_at);
};
```

### 2. Idempotency

```javascript
const processedEvents = new Set();

const handleIdempotentEvent = async (event) => {
  if (processedEvents.has(event.id)) {
    console.log(`Event ${event.id} already processed`);
    return;
  }

  await processEvent(event);
  processedEvents.add(event.id);
};
```

## Next Steps

- [Webhook Overview](/docs-v2/webhooks/overview)

---

# AI Chat with Pay-per-Request

Section: Integration Guides
URL: https://monetize.software/docs-v2/guide/ai-chat

Step-by-step guide to creating an AI chat with token-based monetization. Users pay for each AI request, allowing fair distribution of API costs and revenue generation.

## What We'll Build

In this guide, you'll set up:

- ✅ Tokenized paywall with different request types
- ✅ AI API Provider for OpenAI/Claude integration
- ✅ Automatic token deduction for requests
- ✅ Balance top-up system
- ✅ Chat interface with balance checking

## Solution Architecture

---
## Setting up Payment Infrastructure

### Step 1: [Create paywall](/docs-v2/payment-processor/create-payment-processor)
Create Tokenized Paywall

### Step 2: [Create payment processor](/docs-v2/payment-processor/create-payment-processor)

### Step 3: [Connect payment processor to paywall](/docs-v2/payment-processor/connect-payment-processor)

### Step 4: [Install client-side SDK](/docs-v2/sdk-v2/client-side/install-paywall)

## Setting up AI API Provider

### Step 4: Create API Provider

1. Go to **"API Providers"** → **"New API Provider"**
2. Fill in OpenAI configuration:

**Basic OpenAI Setup:**
```json
Name: OpenAI GPT-4 Chat
URL: https://api.openai.com/v1/chat/completions
Method: POST
Query Price Level: Standard

Headers:
{
  "Authorization": "Bearer YOUR_OPENAI_API_KEY",
  "Content-Type": "application/json"
}

Body:
{
  "model": "gpt-4",
  "max_tokens": 500,
  "temperature": 0.7
}
```

### Step 5: Configure Different Request Levels

Create multiple API Providers for different request types:

    **OpenAI Basic Chat:**
    ```json
    Query Price Level: Basic
    Body: {
      "model": "gpt-3.5-turbo",
      "max_tokens": 150,
      "temperature": 0.7
    }
    ```

    **OpenAI Code Generation:**
    ```json
    Query Price Level: Advanced
    Body: {
      "model": "gpt-4",
      "max_tokens": 2000,
      "temperature": 0.2
    }
    ```

  **Security:** Never expose API keys in frontend code. They should only be stored in API Provider settings on monetize.software servers.

---

## Creating Chat Interface

### React Chat Example

For your actual application, use this full-featured version with real paywall integration:

```jsx
// components/AIChat.js

// URL configuration for different AI models
const model2url = {
  haiku: `https://appbox.space/api/v1/api-gateway/{{YOUR_API_PROVIDER_ID}}?paywall_id={{YOUR_API_PAYWALL_ID}}`,
  sonnet: `https://appbox.space/api/v1/api-gateway/{{YOUR_API_PROVIDER_ID}}?paywall_id={{YOUR_API_PAYWALL_ID}}`,
  opus: `https://appbox.space/api/v1/api-gateway/{{YOUR_API_PROVIDER_ID}}?paywall_id={{YOUR_API_PAYWALL_ID}}`
};

const model2type = {
  haiku: 'standard',
  sonnet: 'advanced',
  opus: 'advanced'
};

export default function AIChat() {
  const [user, setUser] = useState();
  const [messages, setMessages] = useState([]);
  const [answer, setAnswer] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const [prompt, setPrompt] = useState('');
  const [selectedModel, setSelectedModel] = useState('sonnet');
  const abortSignal = useRef({ abort: () => {} });

  const getUser = async () => {
    const user = await paywall.getUser();
    setUser(user);
  };

  useEffect(() => {
    getUser();
  }, []);

  const onSendMessage = async () => {
    if (isLoading) {
      abortSignal.current?.abort();
      setIsLoading(false);
      return;
    }

    if (user?.error) {
      await paywall.open({ resolveEvent: 'signed-in' });
      getUser();
      return;
    }

    setAnswer('');
    setIsLoading(true);
    setPrompt('');

    const newMessages = [
      ...messages,
      {
        role: 'user',
        content: prompt
      }
    ]

    setMessages(newMessages);

    let fullAnswer = '';

    try {
      for await (const chunk of paywall.makeStreamRequest(model2url[selectedModel], {
        method: 'POST',
        body: JSON.stringify({
          messages: newMessages,
          stream: true
        }),
        abortSignal.current
      })) {
        try {
          const lines = chunk
            .split('\n')
            .filter((line) => line.startsWith('data: '));

          lines.forEach((line) => {
            const data = line.replace('data: ', '').trim();
            try {
              const parsed = JSON.parse(data);
              const content = parsed.choices[0].delta.content;
              if (content) {
                fullAnswer += content;
                setAnswer((prev) => prev + content);
              }
            } catch (error) {
              console.error('Failed to parse SSE data:', error);
            }
          });
        } catch (error) {
          console.error('Failed to parse SSE data:', error);
        }
      }

      setMessages((prev) => [
        ...prev,
        {
          role: 'assistant',
          content: fullAnswer
        }
      ]);

      // Charge user queries 
      setUser((user) => ({
        ...user,
        balances: user?.balances?.map((balance) =>
          balance.type === model2type[selectedModel]
            ? { type: balance.type, count: balance.count - 1 }
            : balance
        )
      }));
    } catch (error) {
      if (error === 'not-enough-queries') {
        // User queries have run out, ask to renew subscription to top up again
        setIsLoading(false);
        await paywall.renew();
        // Update user balances after success payment
        await getUser();
      } else if (error === 'Unauthorized' || error === 'access-denied') {
        setIsLoading(false);
        await paywall.open({ resolveEvent: 'signed-in' });
        // Update user balances after success login
        await getUser();
      }
    }

    setIsLoading(false);
  };

  return (
    <div className="chat-container">
      {/* Model selector */}
      <div className="model-selector">
        <select 
          value={selectedModel} 
          onChange={(e) => setSelectedModel(e.target.value)}
          disabled={isLoading}
        >
          <option value="haiku">Claude 4 Haiku (Standard)</option>
          <option value="sonnet">Claude 4 Sonnet (Advanced)</option>
          <option value="opus">Claude 4 Opus (Advanced)</option>
        </select>
      </div>

      {/* Chat messages */}
      <div className="chat-messages">
        {messages.map((message, index) => (
          <div key={index} className={`message ${message.role}`}>
            <strong>{message.role === 'user' ? 'You' : 'AI Assistant'}:</strong>
            <br />
            <span>{message.content}</span>
          </div>
        ))}
        {isLoading && (answer || "Loading answer...")}
      </div>

      {/* Input area */}
      <div className="input-container">
        <textarea 
          onChange={(e) => setPrompt(e.target.value)} 
          value={prompt} 
          placeholder="Write your question" 
          disabled={isLoading}
          rows="3"
        />
        <button onClick={onSendMessage} disabled={!prompt.trim() && !isLoading}>
          {isLoading ? 'Stop' : 'Send message'}
        </button>
      </div>

      {/* Balance display */}
      {user?.balances && (
        <div className="balance-display">
          Your balance:
          {
            user?.balances?.find(
              (balance) =>
                balance.type === model2type[selectedModel]
            )?.count
          }{' '}
          Queries
        </div>
      )}
    </div>
  );
}
```

## Next Steps

After successfully launching your AI chat, consider adding:

- [Create Offer](/docs-v2/offers/overview)

Congratulations! You've created a fully functional AI chat with monetization. Users can now get quality AI responses while you fairly monetize your service. Now you can connect live payment processor to paywall and start accepting real payments.

---

# Chrome Extension with SDK 3.0

Section: Integration Guides
URL: https://monetize.software/docs-v2/guide/sdk-v3-extension

End-to-end guide for monetizing a **Manifest V3 Chrome extension** using `@monetize.software/sdk-extension`. Bundled npm package — passes CWS review (no remote code, no iframe), shares a single auth/bootstrap state across popup, content scripts, and service worker via an offscreen document.

## What We'll Build

- Extension with popup + content script + service worker, all sharing one user session
- Premium feature gated behind a paywall — opens in the popup, unlock visible everywhere
- Trial counter that decrements across tabs without re-fetching
- Manifest tuned for CWS review (minimal `host_permissions`, no `web_accessible_resources` hack)
- Webhook handler on your backend to sync subscription state

## Why a Separate Package?

A standalone `@monetize.software/sdk` instance in each context (popup, content, SW) would mean three independent auth sessions, three bootstrap fetches, three trial counters. Users would have to log in every time they opened the popup. `@monetize.software/sdk-extension` solves this by running **one** SDK instance inside an offscreen document; popup and content scripts proxy calls to it through `chrome.runtime` ports.

## When You Can Skip the Offscreen Document

The offscreen architecture is needed only when **untrusted or DOM-less contexts** must touch billing:

- **Content scripts on third-party sites** — they run inside a hostile page and must not hold the Bearer token directly (see [Security](/docs-v2/sdk-v3/security)).
- **The service worker** — it has no DOM, so `PaywallUI` can't render there, and Chrome recycles it.

If your only paywall surfaces are **privileged extension-origin pages** — the popup, a **side panel**, a **full-page tab** (`chrome-extension://…`), or the options page — you don't need the offscreen package at all. Those pages already share `chrome.storage.local` (which the SDK auto-detects), can safely hold the Bearer token, and have a DOM for `PaywallUI`. Install the **core** package and instantiate one client per surface:

```bash
pnpm add @monetize.software/sdk
```

```ts

// One instance per surface (popup / side panel / full-page tab / options).
// `auth: true` makes PaywallUI build its own AuthClient + BillingClient;
// reach them via paywall.auth / paywall.billing.
const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});
```

A login, bootstrap or balance update in one surface propagates to the others via `chrome.storage.onChanged` with no extra wiring — that's the same cross-context sync the offscreen variant relies on, minus the proxy. If you also need the metered-AI gateway, build the clients explicitly and call `billing.createApiGatewayClient()`:

```ts

const auth = new AuthClient({ paywallId: '3', apiOrigin: 'https://YOUR_DOMAIN' });
const billing = new BillingClient({ paywallId: '3', apiOrigin: 'https://YOUR_DOMAIN', auth });
const paywall = new PaywallUI({ client: billing, auth, paywallId: '3', apiOrigin: 'https://YOUR_DOMAIN' });
const gateway = billing.createApiGatewayClient();
```

  **Do not write a custom `storage` adapter for this.** Inside an extension the SDK already resolves `chrome.storage.local` automatically (it checks `chrome.runtime.id`) and wires `chrome.storage.onChanged` for cross-context sync. Hand-rolling a `chrome.storage` adapter just re-implements the built-in one, and adding your own key prefix permanently couples the stored session to that adapter. Omit `storage` entirely — supply an adapter only for a genuinely different backend (encrypted store, `sessionStorage`, server-side KV; see [Storage adapters](/docs-v2/sdk-v3/storage)).

**Tradeoff:** each surface runs its own `AuthClient`/`BillingClient`, so two simultaneously-open surfaces each fetch bootstrap and refresh the token on their own timer (with a narrow refresh-rotation race window). Cross-context sync keeps them consistent. If many privileged pages are routinely open at once — or you need content scripts / the SW to read billing — use the single-instance offscreen architecture below instead.

## Architecture

All state lives in the offscreen document. Popup/content render UI; SW is a thin router.

## Set Up the Paywall

### Create the paywall

[Create a paywall](/docs-v2/paywall/create-paywall) and pick **SDK 3.0** as the SDK version. The same paywall works in any browser context (popup, content script, options page) — SDK 3.0 paywalls have no Client / Server mode toggle.

### Add a payment processor

[Create a payment processor](/docs-v2/payment-processor/create-payment-processor) and [connect it](/docs-v2/payment-processor/connect-payment-processor). For extensions, Paddle is often easier (handles VAT/sales tax for digital goods).

### Note your `paywallId`

## Integrate the SDK

### Install

```bash
pnpm add @monetize.software/sdk-extension preact
```

`preact` is a peer dependency — extensions need an explicit copy in their bundle.

### Manifest

```json
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "permissions": ["offscreen", "storage"],
  "host_permissions": ["https://YOUR_DOMAIN/*"],
  "background": { "service_worker": "sw.js", "type": "module" },
  "action": { "default_popup": "popup.html" }
}
```

Add `"identity"` if you enable OAuth in the paywall. Add `"content_scripts"` only if you render the paywall on third-party sites.

  **`host_permissions` for your API origin is optional.** Our API sends `Access-Control-Allow-Origin: *` on `/api/v1/*` with every SDK header allowed, and the SDK fetches with `credentials: 'omit'` — so calls from extension pages, the offscreen document and the service worker all succeed under **plain CORS, without any host permission**. Keep the line only as a hedge: with `host_permissions` the extension bypasses CORS entirely and stays immune to future changes in the API's CORS config. It is **not** needed for cookie auth (the SDK is Bearer-only) and does **not** help content scripts — in MV3 they can't bypass CORS via host permissions, which is exactly why billing routes through the offscreen/background. For the strictest CWS manifest, drop it.

  **Do NOT set `host_permissions: ["<all_urls>"]`** unless your extension genuinely needs to inject content on every site. CWS reviewers manually audit `<all_urls>` extensions, and AV vendors (Avast, Kaspersky) flag them. The SDK itself only needs your API origin.
  See [host_permissions deep-dive](/docs-v2/sdk-v3/installation#host_permissions--что-выбрать).

  **Do NOT add `offscreen.html` to `web_accessible_resources`.** Offscreen documents are created via `chrome.offscreen.createDocument` — a chrome-API call, not a `<iframe src>`. Listing it makes your extension fingerprintable from any page and exposes it to embedding attacks.

### Service Worker — `sw.js`

```ts

installRouter({
  offscreenUrl: chrome.runtime.getURL('offscreen.html')
});
```

That's the entire SW. The router lazily creates the offscreen document the first time popup/content sends a message, and proxies subsequent calls.

### Offscreen — `offscreen.html` loads `offscreen.js`

```html
<!-- offscreen.html -->
<!doctype html>
<script type="module" src="offscreen.js"></script>
```

```ts
// offscreen.ts

startOffscreenServer({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});
```

All HTTP, storage and auth-refresh happens here. Popup/content never touch the network directly.

### Popup — `popup.ts`

```ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});

document.getElementById('upgrade')!.addEventListener('click', () => paywall.open());

paywall.on('purchase_completed', ({ priceId }) => {
  // popup will close shortly after; the unlock is already in storage
});

paywall.on('authChange', ({ event, session }) => {
  if (event === 'SIGNED_IN') {
    // user just signed in — refresh popup UI
  }
  // INITIAL_SESSION fires once per subscriber after the popup mounts — use it
  // to paint the restored state, not as a signal that something just changed.
});
```

### Gate a premium feature in a content script

```ts
// content-script.ts

const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true
});

async function onPremiumAction() {
  const user = await paywall.billing.getUser();
  if (user.has_active_subscription) {
    runPremiumFlow();
    return;
  }
  paywall.open(); // same flow as popup; result is shared
}
```

A purchase from the popup is visible here on the next `paywall.billing.getUser()` call (and via `userChange` event). No reload needed.

## Sync Subscriptions on Your Backend

Same shape as web — see [SaaS Web guide → backend webhooks](/docs-v2/guide/sdk-v3-web#sync-subscriptions-on-your-backend). The only extension-specific note: don't try to persist the canonical user state in `chrome.storage` — Chrome wipes extension storage on uninstall/reinstall and on profile switches. Treat the backend (driven by webhooks) as the source of truth.

## CWS Review Checklist

Submitting to the Chrome Web Store with paid features attracts extra scrutiny.

- [ ] `host_permissions` is the **narrowest** set you actually use — for the API origin it's optional (our API is `ACAO: *`, SDK is Bearer + `credentials: 'omit'`); keep only as a CORS hedge or add specific domains if you have content scripts
- [ ] Privacy policy link in the listing covers payment data, email collection, and analytics
- [ ] “Permission justification” fields explain *each* permission with a user-facing reason
- [ ] You don't list `offscreen.html` (or any internal page) in `web_accessible_resources`
- [ ] No remote code execution: all paywall logic ships bundled in your `.zip` — the SDK 3.0 enforces this
- [ ] Single Purpose declaration matches what the extension does (not “monetize stuff”)
- [ ] You test the trial flow with a fresh profile, then a profile that already used the trial

## Production Checklist

- [ ] You handle the offscreen-document lifecycle (Chrome can recycle it; `installRouter` re-creates on demand)
- [ ] Webhook handler in your backend writes to a DB the extension's backend can query — `chrome.storage` is **not** the source of truth
- [ ] If you use trials: backend webhook on `subscription.created` (with `status: trialing`) is what actually starts the trial clock, not the extension
- [ ] You unsubscribe from `paywall.on(...)` listeners when the popup closes (DOMContentUnload)

## Next Steps

- [Installation deep dive](/docs-v2/sdk-v3/installation) — Permissions, manifest variants, Telegram Mini App

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — Cross-context sync via storage.watch

- [Security](/docs-v2/sdk-v3/security) — Token storage in extension contexts

- [Authentication](/docs-v2/sdk-v3/auth) — OAuth in extensions, identity permission

---

# Headless Billing with SDK 3.0 (Server / Custom UI)

Section: Integration Guides
URL: https://monetize.software/docs-v2/guide/sdk-v3-headless

End-to-end guide for using SDK 3.0 **without the built-in UI**. You either render the paywall yourself or proxy AI calls from your backend. The same npm package as for the web — but you import only `@monetize.software/sdk/core` (≤ 8 KB gz, no Preact, no DOM).

## What “Headless” Means Here

SDK 3.0 has three sub-exports of one package:

- `@monetize.software/sdk/ui` — `PaywallUI`, Shadow DOM modal (browser)
- `@monetize.software/sdk/core` — `BillingClient`, `AuthClient`, `ApiGatewayClient`, `EventTracker` (no UI, runs anywhere)
- `@monetize.software/sdk` — both at once

“Headless” = importing **only `/core`**. There is no separate “server-sdk” package and no `server_mode` flag in the dashboard — one `paywallId` serves UI, extension, and headless callers simultaneously.

## What We'll Build

- Server-side checkout: Node backend fetches prices, starts checkout via `BillingClient`, returns a checkout URL to your frontend
- Metered AI proxy: `ApiGatewayClient` forwards user requests to OpenAI/Anthropic and deducts tokens from the user's balance
- Custom upgrade UX: catch `QuotaExceededError`, show your own upgrade screen instead of the built-in modal
- Webhook sync so your DB knows who is paid

## Architecture

## Set Up the Paywall

### Create the paywall

[Create a paywall](/docs-v2/paywall/create-paywall) and pick **SDK 3.0** as the SDK version (no Client / Server mode toggle on SDK 3.0 — every paywall is usable headlessly via `BillingClient`). For metered AI you'll likely want **Tokenized** pricing — see [Tokenization](/docs-v2/paywall/tokenization).

### Add a payment processor

[Create a payment processor](/docs-v2/payment-processor/create-payment-processor) and [connect it](/docs-v2/payment-processor/connect-payment-processor).

### Add an API Provider (only for metered AI proxy)

In **API Providers** → **New API Provider** configure your upstream (OpenAI / Anthropic / custom). The dashboard issues a `providerId` (UUID) you'll pass to `ApiGatewayClient`. Set per-request token costs in the provider's settings.

### Note your IDs

You'll need `paywallId` (numeric, from paywall URL) and — for the gateway — `providerId` (UUID, from API Providers).

## Server-Side Checkout

The simplest headless scenario: your backend fetches prices and starts checkout on the user's behalf.

### Install

```bash
pnpm add @monetize.software/sdk
```

### Initialize on your backend

```ts
// server/billing.ts

// One instance per process. apiKey identifies you (the paywall owner);
// per-request identity is set just before the call (next step).
export const billing = new BillingClient({
  paywallId: process.env.MONETIZE_PAYWALL_ID!,
  apiOrigin: 'https://YOUR_DOMAIN',
  apiKey: process.env.MONETIZE_API_KEY! // server-only key from the dashboard
});
```

`apiKey` is generated in Dashboard → Settings → API keys. **Never put it in client code** — the SDK warns if it detects `window`.

  **Bring-your-own auth.** You don't register users in monetize.software's auth — pass their `email` + your stable `userId` per request via `setIdentity` (next step). For endpoints that require Bearer (`listPurchases`, `cancelSubscription`), see [Per-user Bearer](/docs-v2/sdk-v3/headless-server#per-user-bearer).

### Expose prices to your frontend

```ts
// GET /api/prices
app.get('/api/prices', async (_req, res) => {
  const boot = await billing.bootstrap();
  res.json(
    boot.offers.flatMap((o) =>
      o.prices.map((p) => ({
        id: p.id,
        interval: p.interval,
        amount: p.amount,
        currency: p.currency
      }))
    )
  );
});
```

`bootstrap()` is cached — subsequent calls within ~10 minutes hit memory, not the network.

### Start a checkout

```ts
// POST /api/checkout
app.post('/api/checkout', async (req, res) => {
  const user = await yourAuth.requireUser(req); // your own session check

  // Bind this call to the user from your DB.
  billing.setIdentity({
    email: user.email,
    userId: user.id // your stable ID — used to map subscriptions back to your DB
  });

  const checkout = await billing.createCheckout({
    priceId: req.body.priceId,
    idempotencyKey: crypto.randomUUID() // mandatory for production
  });

  res.json({ url: checkout.url });
});
```

Your frontend redirects the user to `checkout.url`. Everything from there (card form, 3DS, success page) is hosted by the payment processor. The webhook (later in this guide) tells you when the subscription is active.

  **`billing` is a singleton — `setIdentity` mutates shared state.** In a long-running worker, call `setIdentity` immediately before `createCheckout` on each request. Don't rely on the previous request's identity sticking around. For multi-tenant or concurrent flows, instantiate a fresh `BillingClient` per request (per [Headless / server-side → Per-request](/docs-v2/sdk-v3/headless-server)).

## Metered AI Proxy with `ApiGatewayClient`

If you sell per-request AI access (chat, image gen, embedding), proxy the calls through Monetize's gateway. It deducts tokens, rejects when balance is empty, and works without `BillingClient`.

### Instantiate the gateway

```ts
// server/ai.ts

const gateway = new ApiGatewayClient({
  paywallId: process.env.MONETIZE_PAYWALL_ID!,
  apiOrigin: 'https://YOUR_DOMAIN',
  userId: 'usr_external_123' // your stable user ID; sent as X-User-ID
});
```

`userId` is **headless-only** — it ships as the `X-User-ID` header. The same client used from a browser would emit a warning, because users could forge the header. Use `auth: <AuthClient>` (Bearer token) on the client.

### Proxy a single request

```ts
// POST /api/ai/chat
app.post('/api/ai/chat', async (req, res) => {
  try {
    const upstream = await gateway.call({
      providerId: process.env.MONETIZE_OPENAI_PROVIDER_ID!,
      path: '/v1/chat/completions',
      method: 'POST',
      body: {
        model: 'gpt-4o-mini',
        messages: req.body.messages
      }
    });

    // .call() returns the raw upstream Response — JSON, SSE, multipart, anything
    res.status(upstream.status);
    upstream.headers.forEach((v, k) => res.setHeader(k, v));
    upstream.body?.pipeTo(/* write to res */ res as any);
  } catch (err) {
    if (err instanceof QuotaExceededError) {
      return res.status(402).json({
        error: 'quota_exceeded',
        currentBalance: err.currentBalance
      });
    }
    throw err;
  }
});
```

### Stream responses

`.call()` returns a `Response`, so SSE / token streaming works without buffering:

```ts
const upstream = await gateway.call({
  providerId,
  path: '/v1/chat/completions',
  body: { model: 'gpt-4o', stream: true, messages }
});
return new Response(upstream.body, { headers: upstream.headers });
```

## Custom Upgrade UX on Quota Exceeded

In headless mode no modal pops up — your code decides what happens. Two patterns:

```ts

try {
  await gateway.call({ providerId, path, body });
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // Return a 402 to your frontend; the frontend opens its own upgrade screen
    // and on confirm calls /api/checkout (above)
    return { needsUpgrade: true, currentBalance: err.currentBalance };
  }
  throw err;
}
```

```ts
const gateway = new ApiGatewayClient({
  paywallId,
  userId,
  onQuotaExceeded: (err) => {
    // Single point of telemetry / Slack alerting / ticket creation
    metrics.increment('quota_exceeded', { user: userId });
  }
});
```

The callback fires *in addition* to the thrown `QuotaExceededError` — useful for cross-cutting concerns.

## Sync Subscriptions on Your Backend

In headless mode webhooks are even more important — there's no UI event to fall back on.

### Subscribe to events

[Create a webhook](/docs-v2/webhooks/create-webhook) for `subscription.*`, `payment.completed`, `refund.created`. See [event payload reference](/docs-v2/webhooks/events).

### Verify and persist

```ts

app.post('/api/webhooks/monetize', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.header('x-signature') ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.MONETIZE_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('bad signature');
  }

  const event = JSON.parse(req.body.toString());

  switch (event.type) {
    case 'subscription.created':
    case 'subscription.updated':
      upsertSubscription(event.data.user.id, event.data.subscription);
      break;
    case 'subscription.cancelled':
      markCancelled(event.data.user.id);
      break;
    case 'refund.created':
      reverseEntitlements(event.data.payment.id);
      break;
  }
  res.send('ok');
});
```

  **Idempotency.** Paddle can resend `subscription.updated` for the same subscription with identical data — your handler must be idempotent. Use the event's `id` as a dedup key in a small table.

## Production Checklist

- [ ] `paywallId`, `providerId`, API keys live in env vars / secret manager, never in code
- [ ] `userId` passed to `ApiGatewayClient` is **stable** for the lifetime of the customer — losing it means a new user with a new trial balance
- [ ] Quota errors return `402 Payment Required` to your frontend (not `500`
- [ ] Webhook handler is idempotent and signature-verified
- [ ] Webhook handler responds `2xx` within 10s — heavy work (emails, syncs) goes to a queue
- [ ] You don't ship `userId` from your browser code — it's headless-only and forgeable from the client
- [ ] If you use streaming AI responses, your frontend handles partial failures (quota can run out mid-stream)

## Next Steps

- [API Gateway deep dive](/docs-v2/sdk-v3/api-gateway) — Balance state, optimistic decrements, providers

- [BillingClient](/docs-v2/sdk-v3/bootstrap) — Bootstrap, prices, checkout flow

- [Authentication](/docs-v2/sdk-v3/auth) — AuthClient methods, anonymous sessions, OAuth

- [Storage adapters](/docs-v2/sdk-v3/storage) — Backing storage for server / mobile / extension

- [Tokenization](/docs-v2/paywall/tokenization) — Per-query pricing setup for AI products

- [Webhook events](/docs-v2/webhooks/events) — Full event payload reference

---

# SaaS Subscription with SDK 3.0 (Web)

Section: Integration Guides
URL: https://monetize.software/docs-v2/guide/sdk-v3-web

End-to-end guide for adding a subscription paywall to a web app / SPA using **SDK 3.0**. Bundled npm package, no iframe, Shadow DOM rendering, built-in auth.

## What We'll Build

- Paywall modal that opens on “Upgrade” click — no iframe, no layout conflicts
- Built-in email / OTP / OAuth login (managed by `AuthClient`
- Subscription gate: check the user's plan on page load, show premium features only to paying users
- Reaction to `purchase_completed` — instantly unlock the feature without page reload

## Architecture

## Set Up the Paywall

### Create the paywall

[Create a paywall](/docs-v2/paywall/create-paywall) and pick **SDK 3.0** as the SDK version. SDK 3.0 paywalls have no separate Client / Server mode toggle — the SDK handles both the modal and headless flows.

### Add a payment processor

[Create a payment processor](/docs-v2/payment-processor/create-payment-processor) (Stripe / Paddle / Chargebee / Freemius), then [connect it to the paywall](/docs-v2/payment-processor/connect-payment-processor). Start in test mode.

### Add subscription plans

In the paywall settings, add at least one recurring plan (e.g. monthly + yearly). Mark one as recommended — it gets the highlight in the modal.

### Note your `paywallId`

Take the numeric ID from the paywall URL in the dashboard — you'll pass it to the SDK.

## Integrate the SDK

### Install

```bash
pnpm add @monetize.software/sdk
# or: npm i @monetize.software/sdk
```

### Initialize once at app boot

```ts
// src/paywall.ts

export const paywall = new PaywallUI({
  paywallId: '3',
  apiOrigin: 'https://YOUR_DOMAIN',
  auth: true // managed AuthClient: email + OTP + OAuth
});
```

`auth: true` is enough for most apps — the SDK creates an `AuthClient` internally, persists the session, and refreshes tokens. If your app already has its own login, you can pass user data into the SDK with [`billing.setIdentity({ email, userId })`](/docs-v2/sdk-v3/bootstrap#setidentityidentity--getidentity) or run the [headless flow](/docs-v2/guide/sdk-v3-headless) entirely from your backend.

### Open the modal

```ts

document.getElementById('upgrade-btn')!.addEventListener('click', () => {
  paywall.open();
});
```

### Gate features by subscription

Use the `BillingClient` exposed on `paywall.billing` to read user state. It's bootstrapped lazily on first call and cached cross-tab via storage events.

```ts

async function gateFeature() {
  const user = await paywall.billing.getUser();

  if (user.has_active_subscription) {
    enablePremium();
    return;
  }

  // Not subscribed — open paywall and wait for purchase
  paywall.open();
}
```

`user.has_active_subscription` is the coarse boolean — covers active subscription, lifetime payment, or active trial. For per-plan logic, walk `user.purchases` (each item has `id`, `status`, `current_period_end`, `cancel_at_period_end`). For renewal / cancel UI, use `billing.listPurchases()` — see [Customer portal](/docs-v2/sdk-v3/customer-portal).

For a side-effect-free check (no `bootstrap` call, no modal mount) prefer `paywall.getAccess()` — it returns a discriminated union `granted | blocked` with `reason: 'has_subscription' | 'trial_blocked' | 'visibility_blocked' | 'no_subscription'`:

```ts
const access = await paywall.getAccess();
if (access.access === 'granted') enablePremium();
else paywall.open();
```

### React to purchase

```ts
const unsubscribe = paywall.on('purchase_completed', ({ priceId, sessionId }) => {
  enablePremium();
  // Optional: tell your backend the user just paid, so you can pre-warm their workspace
  fetch('/api/post-purchase', {
    method: 'POST',
    body: JSON.stringify({ sessionId, priceId })
  });
});

paywall.on('close', () => {
  // user dismissed the modal without buying
});

paywall.on('error', (err) => {
  // network / config errors; payment failures come via 'purchase_failed'
  console.error(err);
});
```

`paywall.on()` returns an unsubscribe function — call it on component unmount. Full event list: [Events](/docs-v2/sdk-v3/events).

## Production Checklist

- [ ] `paywallId` and `apiOrigin` come from env vars, not hardcoded strings
- [ ] In dev you use a test paywall + test payment processor (separate `paywallId`
- [ ] You unsubscribe from `paywall.on(...)` listeners on component unmount (React/Vue)
- [ ] `auth: true` matches your privacy policy — review where the SDK stores tokens ([Security](/docs-v2/sdk-v3/security))

  **Need server-side subscription sync?** Webhooks are the source of truth for the database state — `purchase_completed` can be missed if the tab closes mid-checkout. See the [Headless guide → Sync Subscriptions on Your Backend](/docs-v2/guide/sdk-v3-headless#sync-subscriptions-on-your-backend) for the full handler.

## Next Steps

- [BillingClient API](/docs-v2/sdk-v3/bootstrap) — Bootstrap cache, cross-tab sync, optimistic updates

- [PaywallUI API](/docs-v2/sdk-v3/ui) — All events, options, state machine

- [Authentication](/docs-v2/sdk-v3/auth) — Email / OTP / OAuth, anonymous sessions

- [Security](/docs-v2/sdk-v3/security) — Token storage, CSRF, allowed origins