@nozle-js/node
v0.43.0
Published
Feature Event writes use the Go Engine at `https://api.nozle.app/engine/api/v1/events` (batch: `/events/batch`). Configure `baseUrl` for a custom ingestion endpoint. `eventsUrl` configures Core billing resources and subscription discovery.
Downloads
6,576
Readme
@nozle-js/node
Feature Event writes use the Go Engine at https://api.nozle.app/engine/api/v1/events (batch: /events/batch). Configure baseUrl for a custom ingestion endpoint. eventsUrl configures Core billing resources and subscription discovery.
Server-side Node.js SDK for usage tracking, entitlement checks, margin intelligence, LLM cost capture, and billing management.
Install
npm install @nozle-js/[email protected]Works with both JavaScript and TypeScript. Requires Node.js 18+.
Version 0.13.0 adds captureFetch and recordUsage for usage from any LLM client, createBillingHandler to serve the React billing hooks, webhooks.verify and createWebhookHandler, invoices, usage and balance alerts, currentUsage and pastUsage, a host option and retries (maxRetries, default 2, safe calls only). apiKey is optional and falls back to NOZLE_SECRET_KEY, and every failed call throws NozleApiError. See the changelog and docs.nozle.dev.
Quick Start
import { Nozle } from "@nozle-js/node";
const nozle = new Nozle({ apiKey: "sk_live_..." });
// Track a Feature Event and keep its organization-wide identity.
const transactionId = await nozle.track(
"cust_123",
"copilot_action",
{ mode: "planning" },
);
// Add a detailed provider cost to that Feature Event without waiting for it.
await nozle.costEvents.track({
parentTransactionId: transactionId,
costMeterCode: "ai_tokens",
properties: { model: "gpt-5", type: "input", tokens: 150 },
});
// Entitlement check
const { allowed, reason, used, limit } = await nozle.can("cust_123", "code_completion");
// A customer with several subscriptions: say which one (external ids). Without a selector the result is
// { allowed: false, reason: "subscription_required" }.
await nozle.can("cust_123", "seats", undefined, { subscriptionId: "sub_a" }); // or { entityId: "ent_1" }Configuration
const nozle = new Nozle({
apiKey: "sk_live_...", // Required
baseUrl: "https://api.nozle.app/engine", // Default: https://api.nozle.app/engine
eventsUrl: "https://api.nozle.app/core", // Default: https://api.nozle.app/core
timeout: 15_000, // Default: 10000ms
});LLM Auto-Capture
Automatically extract model name, token counts, and latency from LLM API responses. No manual tracking needed — the SDK intercepts completions and calls nozle.track() for you.
Cost calculation happens server-side via the Go engine's cost model system.
OpenAI
npm install openai # peer dependency, >=4.0.0import OpenAI from "openai";
import { Nozle, wrapOpenAI } from "@nozle-js/node";
const nozle = new Nozle({ apiKey: "sk_live_..." });
const openai = wrapOpenAI(new OpenAI(), nozle, {
customerId: "cust_123",
metricCode: "copilot_action", // customer-facing Feature Event code
costMeterCode: "ai_tokens", // optional detailed Cost Events
feature: "code_completion", // optional analytics property
});
// Use OpenAI normally — tracking happens automatically
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Hello" }],
});
// Streaming works too
const stream = await openai.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Hello" }],
stream: true,
});
for await (const chunk of stream) {
// usage is captured from the final chunk
}Anthropic
npm install @anthropic-ai/sdk # peer dependency, >=0.30.0import Anthropic from "@anthropic-ai/sdk";
import { Nozle, wrapAnthropic } from "@nozle-js/node";
const nozle = new Nozle({ apiKey: "sk_live_..." });
const anthropic = wrapAnthropic(new Anthropic(), nozle, {
customerId: "cust_123",
metricCode: "copilot_action",
costMeterCode: "ai_tokens",
feature: "code_completion",
});
// Use Anthropic normally
const message = await anthropic.messages.create({
model: "claude-sonnet-4-20250514",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }],
});wrapOpenAI and wrapAnthropic return a new client view and never change the client you pass in, so a server can keep one provider client and wrap it per request:
const openai = new OpenAI();
app.post("/chat", async (req) => {
const client = wrapOpenAI(openai, nozle, { customerId: req.team.id });
return client.chat.completions.create({ model: "gpt-4o", messages: req.body.messages });
});Calls on the original client record nothing.
By default each call's usage is sent in the background as soon as the response is read. Pass an event buffer as buffer to queue it there instead, so it is batched and flush() or close() sends it, for example at the end of a serverless handler:
const buffer = nozle.createEventBuffer();
const client = wrapOpenAI(openai, nozle, { customerId: "cust_123", buffer });
await client.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "Hello" }] });
await buffer.flush(); // sends the usage eventcaptureFetch(nozle, { customerId, buffer }) takes the same option. flush() and close() first wait for responses still being read and for their cost events, which are still sent directly. A buffered usage event's delivery failures go to the buffer's onError.
Each provider call creates one Feature Event. When costMeterCode is set, the wrapper generates the Feature Event transaction_id before sending and attaches separate detailed Cost Events for the input, cached_input, cache_write, cache_write_1h, output, reasoning, audio_input, audio_output, image_input and image_output token categories when present (batch_input and batch_output replace input and output for a batch-tier call). Each token is in exactly one category, the cost event ID is <transaction_id>:<type>, and the usage event also carries the breakdowns (cached_input_tokens, reasoning_tokens, ...). A stream that ends early is recorded with stream_aborted: true; tokens the provider did not report are estimated (usage_source: "estimated", bytes / 4). OpenAI and Anthropic field names are normalized into the same Cost Event properties: { tokens, provider, model, type }. Delivery can arrive out of order because the Cost Event processor resolves the shared transaction_id asynchronously.
Usage Tracking
// Basic tracking (Engine picks the customer's one active subscription)
await nozle.track("cust_123", "api_call", { tokens: 100 });
// With explicit subscription
await nozle.track("cust_123", "api_call", { tokens: 100 }, {
subscriptionId: "sub_abc",
});
// With custom transaction ID and timestamp
await nozle.track("cust_123", "api_call", { tokens: 100 }, {
transactionId: "tx_custom_123",
timestamp: "2025-01-15T10:30:00Z",
});Subscription resolution: track() sends external_customer_id and your subscriptionId if given; the SDK does no lookup. Without one, Engine uses the customer's one active subscription. If there are several or none, it answers 422 active_subscription_ambiguous or active_subscription_not_found, thrown as a NozleApiError with that code: pass subscriptionId. currentUsage() and pastUsage() still look the subscription up (cached for 60 seconds).
track() returns the transactionId. The SDK generates a UUID version 7 identifier before sending the request when one is not supplied. The identifier is unique across the Nozle organization and can immediately be reused as a Cost Event parent, including when the two requests arrive out of order.
When track() throws (an error response, a network error or a timeout), the event may still have been recorded. The error carries the transaction ID as error.transactionId, also when the SDK generated it. Retry with that ID and the same event: Engine records an event once per transaction ID, so the retry does not bill it twice. Also pass a timestamp and reuse it on the retry: without one, each attempt is stamped with its own arrival time, and Nozle may count two attempts with different timestamps separately.
const timestamp = new Date().toISOString();
try {
await nozle.track("cust_123", "api_call", { tokens: 100 }, { timestamp });
} catch (error) {
const transactionId = (error as { transactionId?: string }).transactionId;
await nozle.track("cust_123", "api_call", { tokens: 100 }, { transactionId, timestamp });
}const transactionId = nozle.events.createTransactionId();
await nozle.track("cust_123", "copilot_action", {}, { transactionId });
await nozle.costEvents.track({
costEventId: nozle.costEvents.createCostEventId(),
costMeterCode: "ai_tokens",
parentTransactionId: transactionId,
requestId: "provider_request_123",
operationKey: "planning",
properties: { model: "gpt-5", type: "output", tokens: 900 },
});A Cost Event may instead use externalCustomerId without a parent when the cost belongs to a customer but not to one Feature Event. Cost Event methods require a secret key.
Voiding an event
events.void() (secret key) cancels a recorded event by its transaction ID and reverses its usage, credits, cost and margin. It works only while no finalized, open or pending invoice covers the event's time; otherwise it throws NozleApiError period_invoiced and changes nothing. It is idempotent: a replay returns status: "already_voided".
const { void: v } = await nozle.events.void("tx_123", { reason: "wrong quantity" }); // reason: 1 to 500 characters
// v.status "voided" | "already_voided"; v.effects.credits "refunded" | "not_applicable" | "pending"Refusals: event_not_found (404), period_invoiced (409), reason_required (422); test with error.hasCode(EventVoidErrorCode.PeriodInvoiced). A voided ID cannot be tracked again (transaction_voided, 409): send the corrected event with a new transactionId. An effect is pending while its background step runs; replay the call to read the current state.
Batching events
trackBatch() sends many events through Engine's /events/batch in one call. It takes the arguments of track() as objects, splits them into requests, sends them in parallel and returns one result per event.
const result = await nozle.trackBatch([
{ customerId: "cust_123", event: "api_call", metadata: { tokens: 100 } },
{ customerId: "cust_456", event: "api_call", metadata: { tokens: 40 }, timestamp: "2026-10-29T09:30:00Z" },
]);
console.log(result.accepted, result.rejected, result.failed);
for (const r of result.results) {
if (r.status === "rejected") console.warn(r.index, r.errors); // { code: ["value_is_mandatory"] }
if (r.status === "failed") console.error(r.index, r.transactionId, r.error); // resend with this transactionId
}The contract:
- Size. At most 5000 events per request: the Engine 2.28.0+ default (
LAGO_EVENTS_BATCH_MAX_LENGTH).chunkSize(1 to 5000, default 5000) sets the size of each request, and a longer list is split.concurrency(1 to 64, default 4) is how many requests are in flight at once. Each request body is gzipped (Content-Encoding: gzip, Engine 2.28.0+); the decoded body limit is 16 MiB. An Engine with a lower cap (before 2.28.0 the default was 100) answers 422too_many_eventsand stores nothing; the SDK then sends that request in halves until each fits. - Result.
results[i]belongs toevents[i]and has astatus:accepted(stored),rejected(Engine refused this event;errorsmaps a field to codes, and resending it unchanged fails again) orfailed(its request failed:erroris aNozleApiError, a network error or a timeout, and the event may or may not be stored).accepted,rejected,failedandtotalcount them.trackBatch()throws only for invalid arguments; a failed request never hides the results of the others. - Partial acceptance. Engine 2.28.0+ stores the valid events of a request and answers 200 with
error_detailsnaming each refused event by position: an invalid event, atransactionIdalready stored with other values, or an event of a customer whose payment is overdue (customer_payment_overdue). The SDK marks thoserejectedand the othersaccepted. A request that stores nothing (every event refused, or an Engine before 2.28.0, which refuses a whole request for one bad event) answers 422 or 402 naming the bad events; the SDK marks thoserejectedand resends the valid rest (at most 3 requests for one chunk), so one bad event costs its own result only. A 5xx or network error still fails the whole request; it is retried as below. - Idempotency. Every event has a
transactionId: yours, or a generated UUID version 7 that is also returned inresults[i].transactionId. Engine records an event once per transaction ID, so the SDK retries a request after a network error, timeout, 429 or 5xx (maxRetries, default 2) without storing an event twice. IDs must be unique in one call (NozleValidationErrorotherwise). To retryfailedevents yourself, pass the sametransactionIdand the sametimestamp. - Timestamps. Each event keeps its own
timestamp(RFC 3339 or Unix seconds); without one Engine stamps it on arrival. There is no backfill flag:/events/batchaccepts old and future timestamps as sent. It does not apply the 24 hours ahead and 366 days back window thatusage.track()and cost events enforce. - Subscription. As for
track(), passsubscriptionIdor let Engine resolve the customer's one active subscription. A customer with several or none is a 422 for that event, so it comes backrejected. - Invalid arguments (
NozleValidationErrorwith the event'sindex, before any request): a missingcustomerIdorevent, a badtimestamp, a repeatedtransactionId, or an out-of-rangechunkSizeorconcurrency.
trackBatch() is not usage.track(): it records events like track() does and does not deduct credits, apply a money-billed feature's checks or return a balance. A list of 0 events sends nothing. To batch events as they happen, use an event buffer.
Event buffer
createEventBuffer() queues events in memory and sends them through trackBatch() in the background, so recording an event never waits for the network.
const buffer = nozle.createEventBuffer({
onError: (error, events) => console.error(error.code, error.message, events.map((e) => e.transactionId)),
});
const transactionId = buffer.track({ customerId: "cust_123", event: "api_call", metadata: { tokens: 100 } });
// At shutdown, or at the end of a serverless handler:
await buffer.close();track(event)takes atrackBatch()event and returns its transaction ID at once, without a request: yours, or a generated UUID version 7. Every resend of the event carries that ID, so Engine records it once. It throwsNozleValidationErroronly for an invalid event (missingcustomerIdorevent, badtimestamp).When it sends. A flush starts as soon as
maxBatchSizeevents are waiting (default 500, 1 to 5000; also the size of each request), everyflushIntervalMs(default 5000; 0 disables the timer) and on the process'sbeforeExit. The timer never keeps the process alive. Only one flush runs at a time; a trigger during a flush waits for it.Backoff. After a flush in which any event failed, the size, timer and
beforeExitflushes pause for 1 s, doubling after each consecutive flush with failures up to 60 s; a flush without failures ends the pause. Events keep queueing meanwhile (up tomaxQueueSize), so a short outage costs no events. An explicitflush()orclose()does not wait.await flush()sends every event waiting now and resolves when done; it never rejects.await close()stops the timer, removes thebeforeExithook, sends everything (retrying failures as below) and refuses later events.sizeis the number of events waiting.Bounded memory. The buffer holds at most
maxQueueSizeevents (default 10 000), including those in a request. When it is full,track()drops the new event and reports it asbuffer_full; it does not throw.Never silent.
onError(error, events)receives anEventBufferErrorfor every event that leaves the buffer unsent, witherror.code:buffer_full: the queue was full and the new event was dropped.rejected: Engine refused the event;error.errorsmaps a field to codes. It is not retried.failed: its requests failed (after themaxRetriesof each request) inmaxAttemptsflushes (default 3), spaced by the backoff above. Until then a failed event goes back to the front of the queue for the next flush;error.causeis the last error.closed:track()was called afterclose().
Without
onError, each is emitted as aNozleTrackingWarningprocess warning.onErrormust not throw.
Serverless (AWS Lambda, Vercel and Cloudflare functions, and similar): the platform may freeze or end the process as soon as the handler returns, so neither the timer nor beforeExit runs. Always await buffer.flush() (buffer kept between invocations) or await buffer.close() (buffer per invocation) before returning, or the waiting events are lost. flush() keeps a failed event queued for a later flush; only close() retries it to maxAttempts and reports it, so short-lived processes and scripts should end with await buffer.close().
The queue lives in memory only: events still waiting when the process is killed (for example SIGKILL, or process.exit(), which skips beforeExit) are lost. During a backoff, beforeExit only sets a timer that does not keep the process alive, so a process whose server stays unreachable still exits and its waiting events are lost without a report unless it called close(). wrapOpenAI, wrapAnthropic and captureFetch queue their usage events in a buffer passed as their buffer option.
Entitlement Checks
const result = await nozle.can("cust_123", "code_completion");
if (result.allowed) {
console.log(`${result.remaining} uses remaining`);
} else {
console.log(`Blocked: ${result.reason}`);
}Response includes cost intelligence:
result.economics?.estimated_incremental_cost // Exact decimal string, for example "0.05"
result.economics?.estimated_incremental_revenue // Exact decimal string, for example "0.10"
result.economics?.estimated_incremental_margin // Exact decimal string, for example "0.05"
result.economics?.estimated_margin_percent // Percentage string when revenue is above zero
result.policy?.decision // "allow", "warn", or "deny"
result.policy?.scope // "customer", "plan", "feature" or "organization" (Engine 2.40.0)
result.policy?.on_not_configured // "allow", "warn" or "deny" for a feature with no Cost Rule (Engine 2.39.0)Credit Check & Deduct
checkAndDeduct is a legacy wallet adapter. New product-credit integrations should use nozle.usage.check() and nozle.usage.track() so metric conversion, source ordering, idempotency, and the immutable ledger remain authoritative.
Advisory checks return exact-decimal projected_remaining and ordered
projected_deductions. These fields show the source plan without changing a
balance and are suitable for shadow comparisons before a metric canary.
const result = await nozle.checkAndDeduct({
customerId: "cust_123",
credits: 5,
});
// `feature` is deprecated: it is accepted for old callers but never sent.
if (result.allowed) {
console.log(`Deducted. Remaining: ${result.remaining}`);
} else {
console.log(`Insufficient credits. Balance: ${result.remaining}`);
}Customer Management
Customer writes go directly to Nozle Core using the merchant's secret key, so Core derives the owning organization from that key.
// Create or update a customer
const customer = await nozle.customers.upsert({
externalId: "cust_123",
name: "Acme Corp",
email: "[email protected]",
});
// Link a customer that already exists in Stripe, without creating a new one
await nozle.customers.upsert({
externalId: "cust_123",
billingConfiguration: {
paymentProvider: "stripe",
paymentProviderCode: "stripe_main",
providerCustomerId: "cus_ABC123",
},
});Tax data: pass customerType, legalName, address, shippingAddress and taxId. Core validates the format (value_is_invalid, value_is_mandatory, invalid_format in errorDetails; test with error.hasCode(CustomerTaxErrorCode.InvalidFormat)). A VIES check can leave tax_identification_status at pending, so wait before checkout:
await nozle.customers.upsert({
externalId: "cust_123",
customerType: "company",
address: { line1: "Main St 1", city: "Berlin", postalCode: "10115", country: "DE" },
taxId: { type: "eu_vat", value: "DE811128135" }, // null clears it
});
const customer = await nozle.customers.waitForTaxCheck("cust_123"); // { timeoutMs } defaults to 10000
customer.tax_treatment; // "reverse_charge" | "standard" | ...Pass taxExempt: true to exempt a customer from tax. An invoice with tax_status: "failed" carries one of CustomerTaxErrorCode.TaxLocationInvalid, TaxIdInvalid, StripeTaxNotAuthorized, StripeAccountRequired or TaxProviderUnavailable.
A checkout call refuses with customer_tax_location_required (422) when the billing entity needs a country or address, and customer_tax_check_pending (409, error.retryAfterSeconds) while a check runs.
A payment provider assignment needs providerCustomerId or syncWithProvider: true; otherwise Core drops it. The same applies to provider_customer_id and sync_with_provider when you call the REST API directly.
Deleting and erasing a customer
customers.delete(externalId) deletes the customer and ends its subscriptions. It is not an erasure: the customer's personal data stays. customers.erase(externalId) erases that personal data (GDPR), irreversibly, and returns the customer with erased_at set; Core finishes in the background and sends a customer.erased webhook. Erase refuses with 422 while the customer has active subscriptions or draft or unpaid invoices. Erasing an erased customer changes nothing. Neither call is retried automatically.
try {
const customer = await nozle.customers.erase("cust_123");
customer.erased_at; // "2026-11-18T10:00:00Z"
} catch (error) {
if (error instanceof NozleApiError && error.hasCode(CustomerEraseErrorCode.HasUnpaidInvoices)) {
// collect or void the open invoices first
}
}Importing billing state and opening credit balances
When you move customers from another billing system, import each subscription that system still bills, then its current credit balance. Both calls need a secret key and an idempotencyKey (at most 255 bytes): retry an uncertain call with the same key and the same body. dryRun: true validates without writing.
const imported = await nozle.customers.importBillingState(
"workspace_123",
{
subscription: {
planCode: "pro_monthly",
status: "active",
billingAuthority: "external",
externalReference: "merchant_subscription_123",
currentPeriodStart: "2026-10-15T00:00:00Z",
currentPeriodEnd: "2026-11-15T00:00:00Z",
},
},
{ idempotencyKey: "import-workspace_123-state" },
);
await nozle.customers.importCreditBalance(
"workspace_123",
{
externalSubscriptionId: imported.subscription.external_subscription_id!,
creditSystemCode: "ai_credits",
grantedAmount: "500",
remainingAmount: "320",
},
{ idempotencyKey: "import-workspace_123-credits" },
);Failures throw NozleApiError; for example error.code === "idempotency_key_reused" when a key is reused with a different body.
Product credits
Read exact-decimal balances and immutable operation history from the Phase 1 credit engine:
const balance = await nozle.credits.getBalance("cust_123", "ai_credits");
const page = await nozle.credits.listOperations("cust_123", {
creditSystemCode: "ai_credits",
limit: 25,
});Keep these reads on the merchant backend. Return only the fields your authenticated browser route needs, and derive the customer from the logged-in user or team instead of trusting a browser customer ID.
Credit holds
When a call's final amount is known only afterwards (an LLM response, a long job), reserve credits first and settle afterwards. Needs Engine 2.34.0+ and a secret key.
const hold = await nozle.usage.holds.create(
{ customerId: "cust_123", featureCode: "agent_execution", properties: { tokens: 4000 }, ttlSeconds: 600 },
{ idempotencyKey: `hold-${runId}` },
);
if (!hold.allowed) throw new Error(hold.reason); // "insufficient_credits": nothing was reserved
try {
const answer = await runAgent();
await nozle.usage.holds.finalize(hold.hold_id, { properties: { tokens: answer.tokens } });
} catch (error) {
await nozle.usage.holds.release(hold.hold_id);
throw error;
}create(params, { idempotencyKey })takes theusage.track()params plusttlSeconds(1 to 86400, default 900). A short balance answersallowed: false, not an error; a retry with the same key gets the same answer.finalize(holdId, { properties, timestamp })spends the actual usage at the rate pinned by the hold and releases the rest (credits_released). More than was held passes when the hold plus free credit covers it; otherwiseallowed: falseand the hold stays open. After expiry it runs as a plain track (hold_expired: true). A repeat with the same usage replays the answer, so it is retried likeusage.track().release(holdId)is idempotent; a finalized hold throwsNozleApiErrorwithcodehold_already_resolved(409).get(holdId)andlist(customerId, { status })(held,denied,finalized,released,expired; newest 100) read holds; anotherstatusthrows before any request. A missing hold throwshold_not_found(404).- Balances gain
held(and each sourceheld; entity balancesentity_held,shared_held);availablealready excludes open holds. - As with
usage.track(), a timestamp the SDK fills in is kept per idempotency key (and per hold forfinalize) in this client's memory. Passtimestampwhen a retry may come from another process.
Money budgets
Spend limits (Core) cap what a customer's metered usage may cost per period. Needs Engine 2.34.0+.
import { RefusalReason } from "@nozle-js/node";
const decision = await nozle.can("cust_123", "agent_execution");
if (!decision.allowed && decision.reason === RefusalReason.BudgetExceeded) {
// decision.budget: { limit, spent, held, remaining, currency, period_end, status, ... }
}
const { budgets } = await nozle.budgets.list("cust_123", { subscriptionId: "sub_123" });can(),usage.check()andusage.track()answerallowed: false,reason: "budget_exceeded"withbudgetwhen a hard limit covering the Feature is used up; a soft limit never refuses. ComparereasonwithRefusalReasonvalues; unknown reasons arrive as their string.- A plain
can()is check-then-call, so calls in flight can overrun a cap. For an exact cap, take a hold: on a Feature billed in moneyusage.holds.create()returns a budget hold (kind: "budget",amount_held,currency) and refuses withbudget_exceededwhen the estimated spend does not fit. - Where a failed response throws, a 402
budget_exceededis aBudgetExceededError(withbudgetwhen sent) and a 429usage_limit_exceededaUsageLimitExceededError; both extendNozleApiError. Through the LLM proxy the provider SDK's own error carries the samecode.
Entities and per-user credits
Use Entities for stable customer-owned subjects such as workspace users. Entity mutations require a server-side secret key and a caller-supplied idempotency key.
await nozle.entities.upsert(
"workspace_123",
"user_42",
{ name: "Asha", status: "active", metadata: { role: "agent" } },
{ idempotencyKey: "entity-user-42-v1" },
);
const entities = await nozle.entities.list("workspace_123", {
status: "active",
limit: 50,
});
const balance = await nozle.credits.getEntityBalance(
"workspace_123",
"user_42",
"ai_credits",
);
console.log(balance.entity_available);
console.log(balance.shared_available);
console.log(balance.effective_available);Entity subscription checkout
Create one payment for a mixed basket of Entity plans from your trusted backend:
const checkout = await nozle.entitySubscriptions.checkoutMany("workspace_123", {
billingTime: "anniversary",
returnUrl: "https://app.example.com/settings/billing",
idempotencyKey: "workspace-123-seat-purchase-v1",
items: [
{ externalEntityId: "seat_pro_001", planCode: "pro_monthly" },
{ externalEntityId: "seat_max_001", planCode: "max_monthly" },
],
});For Stripe the result is type: "hosted": redirect the customer to checkout.url. After they return, confirm the outcome as described under
"Payment providers" below (a Stripe checkout_id is not a status id). Never expose the secret Nozle key
to the browser.
Allocation and deallocation preserve exact decimal strings, source provenance, and expiry. They are backend-only operations and may also be disabled by the Engine's exact organization/Credit System rollout gate.
await nozle.credits.allocate(
"workspace_123",
"user_42",
{ creditSystemCode: "ai_credits", amount: "100.000000000001" },
{ idempotencyKey: "allocate-user-42-100" },
);
await nozle.usage.track(
{
customerId: "workspace_123",
entityId: "user_42",
featureCode: "agent_execution",
creditSystemCode: "ai_credits",
},
{ idempotencyKey: "execution-0183f" },
);Keep the same idempotency key when retrying an uncertain mutation result. Never convert credit amounts to JavaScript numbers.
Workspace suspended or card required (402)
When your Nozle workspace is suspended because its Nozle invoices are unpaid, every API call answers HTTP 402 with code workspace_suspended. A workspace without a verified card answers 402 with code card_required the same way. NozleApiError has status 402 and code workspace_suspended, from can(), track(), usage.check() and every other call; can() throws it instead of returning allowed: false. createBillingHandler passes the code to the browser.
try {
await nozle.can("cust_123", "code_completion");
} catch (error) {
if (error instanceof NozleApiError && error.code === "workspace_suspended") {
// Tell your team to pay the Nozle invoices; do not treat this as allowed or denied.
}
}Never retry blindly: the SDK does not retry a 402. Add a card in the Nozle dashboard (card_required) or pay the Nozle invoices (workspace_suspended) and calls work again at once. Events sent during the suspension are refused, not queued.
Customer payment overdue (402)
When one of your customers leaves invoices unpaid past the plan's grace (your dunning settings), Nozle refuses that customer's usage with HTTP 402 and code customer_payment_overdue until the invoices are paid. Other customers are not affected.
can()returns{ allowed: false, reason: "customer_payment_overdue", used: 0, limit: null, remaining: null }instead of throwing. Show the customer that a payment is overdue and link to your billing page.track(),usage.check()andusage.track()throwNozleApiErrorwithstatus402;error.hasCode(CUSTOMER_PAYMENT_OVERDUE)is true. Nothing is recorded./events/batchstores the other customers' events and answers 200 witherror_detailskeyed by the index of each refused event (EventBatchResponse);refusedEventIndexes(body.error_details, CUSTOMER_PAYMENT_OVERDUE)lists them. When every event is refused it answers 402 and stores nothing;error.refusedEventIndexes(CUSTOMER_PAYMENT_OVERDUE)lists them on theNozleApiError.- The LLM proxy answers 402 with
codecustomer_payment_overduefor theX-Nozle-Customer-Idcustomer before the provider is called.isCustomerPaymentOverdue(error)is true for that error from the Anthropic SDK (it keeps the body inerror) and for aNozleApiError. The OpenAI SDK drops a top-levelcode; with it, callcan()before the request to read the reason.
import { CUSTOMER_PAYMENT_OVERDUE, refusedEventIndexes, type EventBatchResponse } from "@nozle-js/node";
const { allowed, reason } = await nozle.can("cust_123", "code_completion");
if (reason === CUSTOMER_PAYMENT_OVERDUE) {
// Ask the customer to pay the open invoice.
}
const res = await fetch(`${nozleUrl}/api/v1/events/batch`, { method: "POST", headers, body: JSON.stringify({ events }) });
const body = (await res.json()) as EventBatchResponse;
const refused = refusedEventIndexes(body.error_details, CUSTOMER_PAYMENT_OVERDUE); // stored: every other eventWebhooks
nozle.webhooks.verify({ body, headers, secret }) checks a delivery against the raw body and returns the parsed event, or throws WebhookVerificationError. Pass the endpoint's whsec_ secret; during a rotation pass both secrets as an array. The check uses webhook-id, webhook-timestamp and webhook-signature, rejects timestamps more than 300 seconds off (toleranceSeconds changes this) and makes no network call.
import { createWebhookHandler } from "@nozle-js/node";
export const POST = createWebhookHandler(nozle, {
secret: process.env.NOZLE_WEBHOOK_SECRET,
onEvent: async (event) => { /* event.id is the same on every retry: skip duplicates */ },
});Credit notes and refunds
Needs a secret key and a workspace with credit notes enabled (otherwise NozleApiError 403 feature_unavailable). A credit note lowers a finalized invoice; its total is settled by crediting the customer's balance, refunding the original payment method (Stripe or Razorpay, started by Nozle), offsetting what the customer still owes, or a mix.
const items = [{ feeId: "fee_123", amountCents: 500 }]; // feeId: `fees[].nozle_id` in the invoice from GET /invoices/{id}
// 1. Preview: nothing is created. Taxes and coupons are applied.
const preview = await nozle.creditNotes.preview({ invoiceId: "inv_123", items });
preview.max_creditable_amount_cents; // the credit note's total
preview.max_refundable_amount_cents; // what was paid and not refunded yet
// 2a. Refund the items to the original payment method (partial refunds: use fewer or smaller items).
const note = await nozle.creditNotes.refund({ invoiceId: "inv_123", items, reason: "duplicated_charge", metadata: { ticket: "T-42" } });
note.refund_status; // "pending", then "succeeded" or "failed" (webhook credit_note.refund_failure)
// 2b. Or choose the split yourself: the three amounts add up to max_creditable_amount_cents.
await nozle.creditNotes.create({ invoiceId: "inv_123", items, refundAmountCents: 300, creditAmountCents: 200, reason: "order_change" });
// 2c. Money you already paid back yourself (bank transfer, cash): the out-of-band part of the refund is recorded, never sent to a provider.
await nozle.creditNotes.create({ invoiceId: "inv_123", items, refundAmountCents: 500, outOfBandRefundAmountCents: 500, outOfBandRefundReference: "TRX-42" });
await nozle.creditNotes.list({ customerId: "cus_1", refundStatus: "failed" });
await nozle.creditNotes.get(note.nozle_id);
await nozle.creditNotes.void(note.nozle_id); // voids the unused credit; never undoes a paid refund or an offsetreason is one of duplicated_charge, product_unsatisfactory, order_change, order_cancellation, fraudulent_charge, other (default). refund() throws refund_exceeds_paid_amount and creates nothing when less was paid than the items are worth; pass creditRemainder: true to refund what was paid and credit the rest.
The SDK sends no Idempotency-Key with credit note requests yet (Core 11.22.0 accepts one on create), so create(), refund() and void() are never retried, whatever maxRetries says; preview(), get() and list() are. After a network error or a 5xx on create(), call list({ customerId, invoiceNumber }) before trying again. Errors are NozleApiError; test them with error.hasCode(CREDIT_NOTE_ERROR_CODES.cannotRefundUnpaidInvoice) (also higherThanRemainingInvoiceAmount, higherThanRemainingFeeAmount, doesNotMatchItemAmounts, invalidTypeOrStatus, noVoidableAmount). From Core 11.46.0 an online refund the invoice's provider payments cannot take is refused with manualRefundRequired (manual payment, or only marked paid), providerRefundUnsupported (a provider Nozle cannot refund through) or insufficientRefundableAmount; record it with outOfBandRefundAmountCents instead (higherThanRefundAmount when that is above refundAmountCents). Nozle stores only the provider's refund id and status, never card or bank details.
Health Check
const status = await nozle.ping();
// { ok: true, engine: "ok" }Margin Intelligence
Requires a secret key (sk_ prefix).
const summary = await nozle.margin.summary();
const byCustomer = await nozle.margin.byCustomer();
const byMetric = await nozle.margin.byMetric();
const byPlan = await nozle.margin.byPlan();
const byModel = await nozle.margin.byModel();
const trend = await nozle.margin.trend({ granularity: "day" });
const simulation = await nozle.margin.simulate({ metricCode: "agent_execution", newPriceDollars: 1 });
// With time range
const q1 = await nozle.margin.summary({
from: "2025-01-01T00:00:00Z",
to: "2025-03-31T23:59:59Z",
});Cost Intelligence
const report = await nozle.costIntelligence.report({ from: "2026-10-01T00:00:00Z", limit: 50 });
const preview = await nozle.costIntelligence.previewSharedCostAllocation(poolId, {
allocationPeriodStart: "2026-10-01T00:00:00Z",
});
// Books a closed period now; Nozle also books it within about 15 minutes of the close.
const run = await nozle.costIntelligence.allocateSharedCost(poolId, { allocationPeriodStart: "2026-10-01T00:00:00Z" });Plans & Checkout
// List available plans
const plans = await nozle.plans();
// The pricing table view: without plan families and features hidden from it
const visible = await nozle.plans({ includeHidden: false });
// Archived plans (secret key): they take no new subscriptions, existing ones keep billing
const archived = await nozle.plans({ status: "archived" });
// Create checkout from an authenticated merchant route.
const checkout = await nozle.checkout(
"cust_123",
"pro",
"https://merchant.example/billing/complete",
);
// Create subscription after payment
const { subscription_id, status } = await nozle.subscribe("cust_123", "pro");Currencies
A plan family can be sold in several currencies, one plan per interval and currency. With a secret key, plans() lists every plan in every currency; plans({ currency }) lists only that currency, and plans({ externalCustomerId }) only the customer's locked currency (ignored when your organization allows several currencies per customer). A publishable key without currency gets each family's default-currency plans, as the React pricing table shows them. A family plan carries family (code, currencies, default_currency) and prices (every variant: currency, interval, plan_code, amount_cents). An unknown currency is a 422.
checkout() and subscribe() take { planFamilyCode, interval, currency } instead of a plan code; Core picks the variant. Without currency it uses the customer's locked currency, else the family's default. Needs Core 11.10.0.
const eurPlans = await nozle.plans({ currency: "EUR" });
await nozle.checkout("cust_123", { planFamilyCode: "pro", interval: "yearly", currency: "EUR" }, returnUrl);Plan versions
Changing the price of a plan that customers pay for saves it as the plan's next version: new customers get the new version, and existing subscribers keep the price they bought until you move them. plans() returns current versions only; each plan has version and is_current.
// Keep selling the older price to one customer.
await nozle.subscribe("cust_123", "pro", { planVersion: 1 });
const versions = await nozle.planVersions.list("pro"); // every version, its price and active subscriptions
const older = await nozle.planVersions.get("pro", 1);
// Move version 1's subscribers to the current version, each at the end of its billing period.
const preview = await nozle.planVersions.previewMigration("pro", { fromVersion: 1 });
const migration = await nozle.planVersions.createMigration("pro", { fromVersion: 1 });
const detail = await nozle.planVersions.getMigration("pro", migration.nozle_id); // per-subscription items
await nozle.planVersions.cancelMigration("pro", migration.nozle_id); // unschedules moves not startedA migration invoices, credits and refunds nothing when it runs: each subscription is billed the new version from its next period. Subscriptions it cannot move (custom pricing, a trial the new version would change, a pending plan change, an open checkout, and so on) are skipped with a skip_reason. Sending the same plan code again for an existing subscription keeps its version; another planVersion for it is refused. planVersions needs a secret key. See Plan versioning.
Payment providers: Stripe and Razorpay
Nozle collects through the payment provider connected to your organization and assigned to the customer. checkout() and checkoutInvoice() return a result whose type tells you what to do next. Branch on type; a browser callback alone never proves payment.
| type | Provider | Next step |
| --- | --- | --- |
| hosted | Stripe, Razorpay link | Redirect the customer to url (the Stripe Checkout page; payment_url is the same address), then confirm as described below (Stripe: checkout_id is the Stripe session id, not a status id) |
| razorpay | Razorpay | Open the Razorpay modal with key_id, order_id, amount_cents and currency, then verify |
| processing | Razorpay or Stripe | Recover with checkoutStatus(checkout_id) instead of starting another checkout. Razorpay returns it while the order is not ready; Stripe returns it when a quoted upgrade is replayed while its webhook is still pending |
| completed, scheduled | Either | No payment is due now. Credits covered it, or the change takes effect later |
Stripe. Every Stripe checkout is the Stripe-hosted Checkout page; there is no embedded form. checkout_id of a Stripe result is the Stripe session id (cs_...); checkoutStatus does not accept it. An upgrade session lasts 35 minutes, an Entity batch 23 hours. Redirect the customer to url. Pass cancelUrl in the options to choose where Stripe sends a customer who leaves the page (validated like returnUrl, defaults to it). A return URL may contain the literal {CHECKOUT_SESSION_ID}, which Stripe replaces with the Checkout Session id. Credit top-up purchases also return a Stripe-hosted payment_url (valid for 24 hours).
import { Nozle } from "@nozle-js/node";
const nozle = new Nozle({ apiKey: process.env.NOZLE_SECRET_KEY! });
const returnUrl = "https://app.example.com/settings/billing";
const result = await nozle.checkout("cust_123", "pro_monthly", returnUrl, {
cancelUrl: "https://app.example.com/pricing",
});
if (result.type === "hosted") {
// Redirect the customer to result.url.
// Paid upgrade (result.plan_upgrade_intent_id): after they return, poll
// nozle.checkoutStatus(result.plan_upgrade_intent_id, { customerId, subscriptionId });
// status is awaiting_payment (hosted nested), processing, succeeded or expired.
// New subscription or invoice (result.invoice_id): there is no status call. The customer
// returns to your return URL; confirm with the invoice.payment_succeeded or subscription
// webhook, or by reloading billing state (can() or the subscription read).
}A new-subscription checkout retried while the first attempt is unpaid reopens payment for the same invoice when the plan is the same (or returns completed if it was paid meanwhile). For another plan, the unpaid attempt is expired and replaced, or the request gets HTTP 409 subscription_checkout_in_progress (entity_subscription_checkout_in_progress for an Entity checkout) when it cannot be expired yet. Keep the body identical for one idempotency key: a different request with the same key gets HTTP 409 idempotency_key_reused, including an invoice checkout. Checkout error bodies carry status, error and code.
Razorpay. Razorpay supports only INR. Return the razorpay result to the browser, open the modal there, and post the handler's three fields back to your backend. verifyCheckout() sends them to Nozle, which checks the signature and fetches the payment from Razorpay; the SDK does not check the signature locally. Verify and status need an sk_ key.
// Backend: create. `checkout` is { type: "razorpay", checkout_id, key_id, order_id,
// amount_cents (paise), currency: "INR", expires_at, invoice_id | plan_upgrade_intent_id }.
const checkout = await nozle.checkout("cust_123", "pro_monthly", returnUrl, {
idempotencyKey: "checkout-cust_123-pro_monthly-v1",
// registerMandate: true, // UPI AutoPay; the result then also has customer_id,
// // recurring and mandate_max_amount_cents
});
if (checkout.type !== "razorpay") throw new Error("not a Razorpay checkout");
// Browser (after loading https://checkout.razorpay.com/v1/checkout.js):
// new window.Razorpay({ key: checkout.key_id, order_id: checkout.order_id,
// amount: checkout.amount_cents, currency: checkout.currency, handler }).open()
// For a mandate also pass customer_id: checkout.customer_id and recurring: "1".
// Backend: verify what the handler returned (`body` is the JSON your browser posted),
// then poll until both statuses succeed.
const scope = { customerId: "cust_123", subscriptionId: "sub_123" };
await nozle.verifyCheckout(checkout.checkout_id, {
razorpay_order_id: body.razorpay_order_id,
razorpay_payment_id: body.razorpay_payment_id,
razorpay_signature: body.razorpay_signature,
}, scope);
const status = await nozle.checkoutStatus(checkout.checkout_id, scope);
// status.status: awaiting_payment | processing | succeeded | failed | expired | needs_review
// Show success only when status.status and status.fulfillment_status are both "succeeded".Bind each checkout_id to the buyer who started it before you call verify or status. Pass both scope fields to tie a call to one customer and subscription.
Provider errors are NozleApiError instances with status, code and errorDetails. hasCode() matches the top-level code and the codes listed in error_details, for example razorpay_requires_inr, payment_provider_required or invalid_checkout_signature.
import { NozleApiError } from "@nozle-js/node";
try {
await nozle.checkout("cust_123", "pro_monthly", returnUrl);
} catch (error) {
if (error instanceof NozleApiError && error.hasCode("razorpay_requires_inr"))
// Price the plan in INR for customers who pay through Razorpay.
return;
throw error;
}See the Stripe and Razorpay integration guides for connection setup, webhooks, and limits.
Cancel a subscription
Cancellation is server-only and requires an sk_ key. Without a timing, the
organization's cancellation timing applies (set in the dashboard; new organizations default to end_of_period;
existing organizations keep their setting). Pass the timing to choose it per call:
const result = await nozle.cancelSubscription("cust_123", "sub_123", "end_of_period");
// result.subscription.status === "active"
// result.subscription.ending_at === "2026-08-15T00:00:00Z"Pass an options object to also choose how the cancellation is settled. Each option left out follows the subscription, then the organization's cancellation settings:
await nozle.cancelSubscription("cust_123", "sub_123", {
policy: "immediate",
creditAction: "refund", // credit, refund, offset or none
refundMode: "prorated", // prorated or full
finalInvoiceAction: "generate", // generate or skip
});Extend or end a trial
Server-only (sk_ key). trial takes exactly one of extend_days, ends_at or convert, plus an optional reason
(up to 500 characters); giving none or several throws NozleValidationError before any request. A trial can be
extended by at most 90 days at a time and can last at most 365 days in total (the server enforces both).
await nozle.extendTrial("sub_123", { days: 14, reason: "sales call" });
await nozle.extendTrial("sub_123", { endsAt: "2026-12-01T00:00:00Z" }); // at least 30 minutes ahead
const { subscription } = await nozle.convertTrial("sub_123"); // ends the trial now, starts paid billing
// subscription.in_trial === false, subscription.trial_ends_at, subscription.trial_ended_at
await nozle.updateSubscription("sub_123", { trial: { extend_days: 7 } }); // the general callConvert bills at period end on a pay-in-arrears plan and invoices at once on pay-in-advance; payment follows the
normal collection flow and a failed payment does not undo the conversion. Refusals are NozleApiError; test with
error.hasCode(TrialErrorCode.NotActive) (trial_invalid_params, trial_not_active, trial_extension_too_long,
trial_end_in_past, payment_method_required, and plan_change_pending as a 409). These calls are not retried.
TypeScript
All methods and responses are fully typed. Exported types:
import type {
NozleConfig,
TrackOptions,
CanResult,
Plan,
CheckoutResult,
CheckoutStatus,
RazorpayCheckoutResult,
SubscribeResult,
MarginQueryParams,
TrendParams,
PingResult,
CustomerUpsertParams,
CustomerUpsertResult,
CheckAndDeductParams,
CheckAndDeductResult,
WrapOptions,
} from "@nozle-js/node";React billing portal subscription management
See the runnable authenticated merchant integration for Cancel, Keep, payment-backed upgrades, scheduled downgrades, and exact pending-change withdrawal through the React billing portal. It reuses the existing transition methods and derives customer identity from the merchant session. For end-of-period cancellation, optional expectedEffectiveAt preserves the exact preview timestamp and rejects a changed date atomically on compatible Engine/Core deployments. Existing calls without this option remain compatible.
Version 0.9.0 adds subscriptionOptions(customerId, subscriptionId),
previewSubscriptionChange(customerId, subscriptionId, planCode), and
withdrawPendingSubscriptionChange(customerId, subscriptionId, pendingSubscriptionId, idempotencyKey).
Use the existing checkout/transition methods with the selected subscription, signed quote,
and a stable action key. Scope checkoutStatus and verifyCheckout with both customer and
subscription identifiers. See the method examples.
License
MIT. See LICENSE.
