Installation

@nozle-js/node requires Node.js 18 or later and uses the built-in Fetch API. Entity subscription APIs are introduced in 0.5.0.

npm install @nozle-js/node

Create a client

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

export const nozle = new Nozle({
  apiKey: process.env.NOZLE_SECRET_KEY!,
  baseUrl: 'https://api.nozle.app',
  eventsUrl: 'https://core.nozle.app',
  timeout: 10_000,
})

Configuration

Field	Type	Default	Description
`apiKey`	`string`	required	Organization credential. Use a restricted `sk_` for server mutations.
`baseUrl`	`string`	`http://localhost:8080`	API origin used for entitlements, credits, entities, usage, and margin.
`eventsUrl`	`string`	`http://localhost:3000`	Core API origin used for customer writes, billing resources, `track()`, credit-system discovery, and Entity subscriptions. Use `https://core.nozle.app` in production.
`timeout`	`number`	`10000`	Per-request timeout in milliseconds.

Set both URLs explicitly outside local development. Trailing slashes are removed automatically.

This package is server-only. Never bundle an sk_, master key, or internal credential into browser code. Use @nozle-js/react with a publishable key for public catalog reads.

Verify connectivity

const health = await nozle.ping()

console.log(health.ok)
console.log(health.engine)
console.log(health.version)

API surface

API and billing

Method	Purpose
`nozle.ping()`	Check API health.
`nozle.plans()`	List plans.
`nozle.checkout()`	Create a payment-aware checkout result.
`nozle.subscribe()`	Create a direct subscription where your workflow permits it.
`nozle.cancelSubscription()`	Cancel immediately or at the renewal boundary.
`nozle.previewSubscriptionTransition()`	Preview cancellation, downgrade, or uncancel settlement.
`nozle.applySubscriptionTransition()`	Apply an idempotent settlement transition.
`nozle.track()`	Send a metered event through the Events API.
`nozle.can()`	Check feature access, usage, and margin state.

Namespaces

Namespace	Methods
`customers`	`upsert()`
`creditSystems`	`list()`
`entities`	`get()`, `list()`, `upsert()`, `activate()`, `suspend()`, `bulkUpsert()`
`entitySubscriptions`	`ensure()`, `get()`, `list()`, `checkout()`, `changePlan()`, `cancel()`, `remove()`
`credits`	Customer and Entity balance/history reads, `allocate()`, `deallocate()`
`usage`	Advisory `check()` and atomic, idempotent `track()`
`margin`	`summary()`, `byCustomer()`, `byMetric()`, `byPlan()`, `byModel()`, `trend()`

The package also exports wrapOpenAI() and wrapAnthropic() for token metadata capture.

Key behavior

Billing mutations and settlement transitions require an API key beginning with sk_.
Entity mutations, credit transfers, and usage.track() reject publishable pk_ keys.
Mutation idempotency keys are caller-supplied and limited to 255 bytes.
Product-credit amounts are exact decimal strings, not JavaScript numbers.
Failed HTTP responses reject with an Error containing the operation and HTTP status.
Every request uses AbortSignal.timeout(timeout).

Production pattern

Create one client per process and reuse it:

// billing/nozle.ts
import { Nozle } from '@nozle-js/node'

export const nozle = new Nozle({
  apiKey: process.env.NOZLE_SECRET_KEY!,
  baseUrl: process.env.NOZLE_API_URL!,
  eventsUrl: process.env.NOZLE_EVENTS_URL ?? 'https://core.nozle.app',
})

Do not accept authoritative customerId, Entity IDs, plan codes, return origins, or idempotency keys blindly from a browser. Derive or validate them in your trusted backend.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Installation

Create a client

Configuration

Verify connectivity

API surface

API and billing

Namespaces

Key behavior

Production pattern

Next steps

​Create a client

​Configuration

​Verify connectivity

​API surface

​API and billing

​Namespaces

​Key behavior

​Production pattern

​Next steps

Create a client

Configuration

Verify connectivity

API surface

API and billing

Namespaces

Key behavior

Production pattern

Next steps