Quickstart

Create your Nozle account

Get your API keys

From the dashboard, navigate to Settings > API Keys. You will see two keys:

Key prefix	Purpose	Use in
`pk_`	Publishable key	Public plan catalog only
`sk_`	Secret key	Server-side only (Node.js, Python)

Never expose your sk_ secret key in client-side code. Use pk_ only for public pricing and route every customer operation through your authenticated backend.

Install the SDK

Tab Title
Tab Title

npm install @nozle-js/node

pip install nozle-sdk

Initialize the client

Create a Nozle client instance with your secret key.

Tab Title
Tab Title

nozle.ts

import { Nozle } from '@nozle-js/node';

const nozle = new Nozle({
  apiKey: 'sk_...',
  baseUrl: 'https://api.nozle.app',
  eventsUrl: 'https://core.nozle.app',
});

nozle_client.py

from nozle import Nozle

nozle = Nozle(
    api_key="sk_...",
    base_url="https://api.nozle.app",
    events_url="https://core.nozle.app",
)

Track your first event

Send a billable event with metadata. Nozle automatically resolves the customer’s active subscription.

Tab Title
Tab Title

await nozle.track('customer_123', 'api_call', {
  model: 'example-model',
  tokens: 1500,
});

nozle.track("customer_123", "api_call", {
    "model": "example-model",
    "tokens": 1500,
})

Events are matched against your feature definitions in the dashboard. The tokens property can drive usage-based charges, while the event name (api_call) increments count-based meters.

Check entitlements

Before executing an expensive operation, check whether the customer still has capacity on their plan.

Tab Title
Tab Title

const result = await nozle.can('customer_123', 'api_calls');
// {
//   allowed: true,
//   remaining: 8500,
//   limit: 10000,
//   used: 1500
// }

if (!result.allowed) {
  throw new Error('Usage limit reached — upgrade your plan');
}

result = nozle.can("customer_123", "api_calls")
# {
#   "allowed": True,
#   "remaining": 8500,
#   "limit": 10000,
#   "used": 1500
# }

if not result["allowed"]:
    raise Exception("Usage limit reached — upgrade your plan")

The response includes remaining, limit, and used fields so you can show usage progress in your UI.

Add React billing components

Install the React SDK to get pre-built billing UI components.

npm install @nozle-js/react

Use a publishable key for public pricing. Provide a callback that calls your own authenticated backend for checkout:

app/providers.tsx

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

export function Providers({ csrfToken }: { csrfToken: string }) {
  return (
    <BillingProvider
      publishableKey="pk_..."
      createCheckout={async ({ planCode, returnUrl }) => {
        const response = await fetch('/api/billing/checkout', {
          method: 'POST',
          credentials: 'include',
          headers: {'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken},
          body: JSON.stringify({planCode, returnUrl}),
        })
        if (!response.ok) throw new Error('Checkout failed')
        return response.json()
      }}
    >
      <PricingTable returnUrl={window.location.href} />
    </BillingProvider>
  );
}

Your backend authenticates the user, derives their Nozle customer, validates the plan and return URL, and calls Nozle with a restricted secret key.

Show a pricing table and checkout

Drop in a PricingTable to display plans. Its CTA invokes the merchant callback configured above.

app/pricing/page.tsx

import { PricingTable } from '@nozle-js/react';

export default function PricingPage() {
  return (
    <div>
      <h1>Choose your plan</h1>
      <PricingTable returnUrl={window.location.href} />
    </div>
  );
}

Fetch customer entitlements from your backend and pass the result into the presentational FeatureGate:

import { FeatureGate } from '@nozle-js/react';

function AiFeature({ allowed }: { allowed: boolean }) {
  return <FeatureGate allowed={allowed} fallback={<p>Upgrade to continue.</p>}>AI feature</FeatureGate>;
}

What’s next

React SDK, Node.js SDK, and Python SDK
Billing Concepts — plans, metrics, and subscriptions
Entitlements — advanced gating with margin-aware rules

Getting Started

Billing

Product Credits

Margin Intelligence

Entitlements

Create your Nozle account

Get your API keys

Install the SDK

Initialize the client

Track your first event

Check entitlements

Add React billing components

Show a pricing table and checkout

What’s next

​Create your Nozle account

​Get your API keys

​Install the SDK

​Initialize the client

​Track your first event

​Check entitlements

​Add React billing components

​Show a pricing table and checkout

​What’s next

Create your Nozle account

Get your API keys

Install the SDK

Initialize the client

Track your first event

Check entitlements

Add React billing components

Show a pricing table and checkout

What’s next