Quickstart — zero to paywall in 5 minutes

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 — 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

A paywall is created in the dashboard → “Paywalls” → “New Paywall”. Remember the paywallId (the number in the URL).
At least one payment processor is connected (Stripe / Paddle / Chargebee / Freemius).
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, substitute yours.

Pick a scenario

Three integration paths — pick by how much UI you want to own and where your auth lives. See Overview for a side-by-side comparison.

Drop-in (Web)

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


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

Initialize


import { PaywallUI } from '@monetize.software/sdk/ui';
 
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), pass identity or auth: <AuthClient> explicitly.

Open the paywall


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) — the modal still handles preauth signin, popup-blocked retry, and the awaiting-payment screen:


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

React to the purchase


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.

What’s next: BillingClient — when you need prices and user state before opening the modal. Authentication — customising the login flow.

Drop-in (Extension)

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


pnpm add @monetize.software/sdk-extension preact

`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" }
}

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.

Service worker — `sw.js`


import { installRouter } from '@monetize.software/sdk-extension/sw';
 
installRouter({
  offscreenUrl: chrome.runtime.getURL('offscreen.html')
});

Offscreen — `offscreen.html` → `offscreen.ts`


import { startOffscreenServer } from '@monetize.software/sdk-extension/offscreen';
 
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.


import { PaywallUI } from '@monetize.software/sdk-extension';
 
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 — why web_accessible_resources is NOT needed, what to do about <all_urls>, how to pass CWS review.

Custom UI

You render your own pricing cards / login form / “Buy” button; the SDK provides BillingClient for prices/checkout and AuthClient for our auth flows.

Install


pnpm add @monetize.software/sdk

Initialize


import { BillingClient, AuthClient } from '@monetize.software/sdk/core';
 
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();
// prices: [{ id, amount, currency, interval, label, ... }, ...]
// Render them however you want — your JSX, your DOM, your design system.

Wire the “Buy” button


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


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.

What’s next: BillingClient — full method reference. Authentication — every login flow. API Gateway — metered AI calls when you don’t have a backend.

Headless (Server)

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. Same endpoints, language-agnostic specs with curl examples.

Install


pnpm add @monetize.software/sdk

Option A: server-side billing


import { BillingClient } from '@monetize.software/sdk/core';
 
// `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.

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:


// 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 — full server-side guide (apiKey setup, token credit/debit, webhooks, error handling). 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 BillingClient Authentication API Gateway Events Headless / server-side

Quickstart — zero to paywall in 5 minutes

Before you start

Pick a scenario

Drop-in (Web)

Drop-in PaywallUI — Web / SPA

Install

Initialize

Open the paywall

React to the purchase

Drop-in (Extension)

Chrome Extension (MV3)

Install

manifest.json

Service worker — sw.js

Offscreen — offscreen.html → offscreen.ts

Popup / content script

Custom UI

Custom UI — your own pricing page and login

Install

Initialize

Render your own pricing cards

Wire the “Buy” button

Gate a feature

Headless (Server)

Headless (server-side)

Install

Option A: server-side billing

Option B: metered AI billing via debitTokens

What all scenarios have in common

Next steps

`manifest.json`

Service worker — `sw.js`

Offscreen — `offscreen.html` → `offscreen.ts`

Option B: metered AI billing via `debitTokens`