Skip to main content
Nozle API keys have two roles: The browser never receives a Nozle secret key and never chooses the authoritative Nozle customer. Your backend derives that customer from the authenticated application user or team.

Example merchant flow

Backend route

Cookie-authenticated routes must retain normal CSRF protection. The merchant’s secret key should grant only the API permissions required by its backend routes. Never use Nozle’s master key for merchant traffic.

React

Use equivalent authenticated backend endpoints for caller-supplied billing state, entitlements and credits. Return only the fields your browser needs.

Native portal and subscription management

The React billing portal obtains a customer-scoped portal session from your backend for Core GraphQL reads. It uses separate authenticated merchant callbacks for Cancel/Keep, quoted upgrades, scheduled downgrades and withdrawal. These exports and SDK methods are available from React 0.10.2, Node 0.10.0, Python 0.10.0, and Go v0.9.1; the portal guide links the integration examples. Derive the customer from your application session. Accept a selected external subscription ID only after validating its ownership; select eligible targets from subscription options, then confirm a signed quote. Forward the exact quote, cancellation date guard and idempotency key to Nozle. Scope payment verification and recovery to both that customer and subscription. See the HTTP flow and the Node, Python, and Go SDK methods.

Mixed Entity seat purchase

For a seat-pool UI, accept merchant intent such as { proSeats: 2, maxSeats: 1 }, not Nozle customer or subscription identifiers. Your backend:
  1. resolves the customer from the authenticated workspace;
  2. creates or reuses active unassigned Entity placeholders;
  3. assigns one allowed plan code to each placeholder;
  4. sends the complete basket to POST /customers/{customer_id}/entity-subscriptions/checkout with one idempotency key; and
  5. returns the checkout result: an embedded Stripe client secret, a Razorpay order, or a completed result.
Use one bulk request rather than one checkout call per seat. The bulk request creates one invoice, preserves one payment boundary, and aligns later purchases to the customer’s established Entity billing anchor. The browser may decide requested quantities, but the backend owns generated Entity IDs, plan allowlists, customer mapping, billing mode, and return-origin validation. For cancellation, call cancelSubscription(customerId, subscriptionId) from Node.js, cancel_subscription(customer_id, subscription_id) from Python, or CancelSubscription(ctx, customer, subscription, policy) from Go. All three default to end_of_period when the policy is omitted or empty; the raw API keeps its historical immediate default. Resolve the customer from merchant-owned records and validate ownership of the selected external subscription ID. Use the guarded transition flow above for customer-facing Cancel/Keep.

Payment authority

Nozle payment fulfillment is authoritative. A redirect or browser callback alone does not activate a paid plan. Stripe requires backend settlement; Razorpay requires capture. Recover authoritative checkout and subscription state after payment, failures or reloads before reporting activation. Billable and credit-consuming events also stay server-side through the Node, Python, or Go SDK with the restricted sk_. CORS and Origin headers are browser controls, not authentication.