Architecture

​

Overview

​

Trust boundaries

​

Browser

• fetch the public plan catalog with pk_;
• render React SDK components; and
• call your authenticated merchant routes.

​

Merchant backend

• authenticates the application user;
• derives Nozle identifiers from server-owned records;
• validates plan codes and exact return origins;
• calls Nozle with a least-privilege sk_; and
• returns only the fields required by the browser.

​

Nozle API

• plan catalog and subscriptions;
• payment-aware checkout and settlement transitions;
• usage events and invoice aggregation;
• product-credit grants, top-ups, transfers, and atomic consumption;
• entitlement decisions;
• cost models and margin reporting; and
• durable payment and usage-event reconciliation.

​

Payment authority

​

Request flows

​

Entitlement check

Your backend
  -> derives customer from the authenticated user
  -> calls can(customer, feature)
  -> receives allow/deny, usage, and optional margin context
  -> enforces the result before protected work

​

Metered event

Your worker
  -> sends a stable transaction ID and metric properties
  -> Nozle validates and records the event
  -> billing aggregation includes it in the configured period

​

Credit-backed action

Your backend
  -> calls usage.track with an idempotency key
  -> Nozle locks eligible credit sources
  -> records an immutable operation and exact deductions
  -> publishes the matching billing event through a durable outbox

​

Paid checkout

Browser -> merchant backend -> Nozle checkout -> Stripe
Stripe webhook -> Nozle verifies payment -> subscription change applies
Browser refreshes billing state from merchant backend

​

Optional realtime delivery