Billing and subscriptions

Billing methods run on your server with a secret key. Derive the Nozle customer from the authenticated application user or workspace.

List plans

const plans = await nozle.plans()

for (const plan of plans) {
  console.log(plan.code, plan.amount_cents, plan.amount_currency, plan.interval)
}

The Plan type declares code, name, amount_cents, amount_currency, and interval. At runtime each item is the full plan object from the API, including charges, entitlements, taxes and credit_grant_rules, and the list includes trial, pay-in-arrears and pending-deletion plans. See the public plan catalog. With a pk_ key, all of it is readable by anyone who has the key.

Create checkout

const result = await nozle.checkout(
  'workspace_123',
  'pro_monthly',
  'https://app.example.com/settings/billing',
)

checkout() requires an sk_ key. Handle every result discriminator explicitly:

`type`	Fields	Handling
`stripe`	`client_secret`/`clientSecret` (`cs_...`), `invoice_id`, `amount_cents`, `currency`	Mount Stripe embedded Checkout with the client secret. Plan and invoice checkout never return a Stripe `url`; only credit top-ups return a Stripe-hosted `payment_url`. See the Stripe flow.
`razorpay`	`checkout_id`, `key_id`, `order_id`, `amount_cents`, `currency`, `expires_at`, `invoice_id`; with a mandate also `customer_id`, `recurring: true`, `mandate_max_amount_cents`	Open Razorpay Checkout, then verify through your backend. See the Razorpay flow.
`hosted`	`payment_url`	Not returned by `checkout()` or `checkoutInvoice()`. The type still exists for a Razorpay payment link: navigate to `payment_url`. Invoice payment URLs and credit top-ups return a `payment_url` without a `type`.
`processing`	`checkout_id`, `status`	Razorpay: the order is not ready or has expired. Stripe: a replayed quoted upgrade whose webhook is still pending. Recover with `checkoutStatus(checkout_id)`. `status` is an internal operation status.
`completed`	`status: "succeeded"`, `subscription_id`, `plan_code`, `invoice_id` (may be `null`), `amount_cents`, `currency`, `payment_source` (`credits` or `none`)	Refresh authoritative subscription state.
`scheduled`	`status: "pending"`, `subscription_id`, `plan_code`, `transition_direction`, `transition_policy`, `effective_at`	Display the pending plan and its effective date.

A paid upgrade returns plan_upgrade_intent_id instead of invoice_id on stripe and razorpay results. On scheduled, subscription_id is the pending subscription. The CheckoutResult type declares payment_source on completed results. pending_subscription_id was removed from the type in 0.10.0 because the API never returns it; earlier versions declared it. Use the exported CheckoutResult union instead of a reduced local type. Do not treat every non-Stripe response as a scheduled downgrade. React’s checkout components handle these result variants; see checkout components. Validate the exact HTTPS return origin on your server before passing it to Nozle.

Checkout errors

Status	`code`	Cause
400	`invalid_return_url`	The `return_url` origin is not allowed. Checked before anything else.
404	`plan_not_found`, `customer_not_found`	Unknown plan or customer.
409	`subscription_selection_required`	The customer has several active subscriptions and no `subscriptionId` was given.
422	`checkout_not_required`	The plan needs no up-front payment (free, trial, or pay-in-arrears) and the customer has no subscription. Use `subscribe()` instead.
422	`payment_provider_required`	No payment provider is connected.
422	`plan_already_active`	The customer is already on that plan.
409	`subscription_checkout_in_progress`	A payment for the customer’s new-subscription checkout on a different plan is still processing, or it was paid. An abandoned checkout is replaced instead, and the same plan reopens it.

See Create checkout for the HTTP contract.

Nozle payment fulfillment is authoritative. A browser callback or redirect does not prove activation; Razorpay upgrades require capture and Stripe requires backend settlement.

Manage a payment method

const page = await nozle.managePaymentMethod(
  'workspace_123',
  'https://app.example.com/settings/billing',
)

redirect(page.url) // Stripe Billing Portal

Stripe only. Requires an sk_ key. A pk_ key is refused with 403 (no error code, only a message). Nozle stores no card data: the customer changes their payment method in the Stripe Billing Portal. Razorpay customers pay each invoice through a Razorpay payment link, so for them the call fails with 422 razorpay_pays_by_link. See Manage Payment Method for the HTTP contract and error codes.

Direct subscription

await nozle.customers.upsert({ externalId: 'workspace_123', name: 'Acme Workspace' })
const subscription = await nozle.subscribe('workspace_123', 'free')

console.log(subscription.subscription_id)
console.log(subscription.status)

subscribe() requires an sk_ key and returns SubscribeResult. The customer must already exist, so call customers.upsert() first. An unknown customer returns 404 customer_not_found and nothing is created. Calling subscribe() again for the same customer and plan returns the same subscription. It accepts a paid plan without collecting payment. Use checkout for payment-gated plan changes; use direct subscription only where your configured product flow does not require an interactive payment.

subscribe() to another plan adds a second active subscription. It does not replace the first, and plan credit grants are granted again. To move a customer, call checkout() with subscriptionId (needs a transition policy), or cancel and then subscribe. Pass the new subscription ID to track(): cached clients keep the old ID.

Cancellation

const result = await nozle.cancelSubscription(
  'workspace_123',
  'subscription_123',
  'end_of_period',
)

The policy defaults to end_of_period and also accepts immediate.

Subscription self-service

The following subscription-management methods are available from @nozle-js/node 0.10.0. The matching hosted endpoints are available; see the Node merchant example for a complete integration.

These methods power the React billing portal. Use a customer ID derived from your authenticated application session and validate the selected external subscription ID. A Core subscription UUID is not interchangeable with that external ID.

Changing an existing subscription’s plan needs a transition policy for that source and target plan pair. Without one, preview, checkout, and transitions return 422 plan_transition_policy_required. Exception: from a $0 plan to a paid plan, the organization’s free-to-paid default applies without a pair policy.

Load eligible plans and preview a quote

const options = await nozle.subscriptionOptions(customerId, subscriptionId)
const quote = await nozle.previewSubscriptionChange(customerId, subscriptionId, targetPlanCode)

options includes the current subscription, pending_change, policy-authorized eligible_plans, and an optional latest checkout summary. Plans contain code, name, amount_cents, currency, and interval; eligible plans add direction and timing. A pending change has its own internal id and effective_at. The quote includes quote_id, transition_direction, timing, currency, credit_amount_cents, debit_amount_cents, net_amount_cents, amount_due_now_cents, amount_due_at_effective_cents, effective_at, and renewal_at. The API also returns transition_policy, billing_anchor, proration_behavior, and credit_action, which the SDK type omits. Present these exact amounts and dates before confirmation. Monetary values are integer minor units and may be strings; preserve their precision. Do not choose a target solely from the public catalog or by comparing prices.

Confirm a paid upgrade

After the customer confirms, use the saved quote and a stable action key:

const checkout = await nozle.checkout(customerId, targetPlanCode, returnUrl, {
  subscriptionId,
  quoteId: quote.quote_id,
  idempotencyKey: confirmedActionKey,
})

quoteId requires an explicit subscriptionId. A quote expires after five minutes or becomes invalid when its bound state changes. HTTP 409 requires a fresh preview and confirmation. For an uncertain response, retry the same confirmed request with the same key; an accepted request can replay after its quote expires. A $0 to $0 immediate upgrade returns completed with payment_source: "credits" and creates a $0 invoice. An upgrade checkout to a pay-in-arrears plan returns 422 plan_upgrade_invoice_missing.

Schedule or withdraw a downgrade

For a confirmed quote whose transition_direction is downgrade:

const scheduled = await nozle.applySubscriptionTransition({
  customerId,
  subscriptionId,
  operation: 'downgrade',
  targetPlanCode,
  timing: 'end_of_period',
  billingAnchor: 'keep_anchor',
  quoteId: quote.quote_id,
}, confirmedActionKey)

Reload options to show the pending plan separately from the active plan. To withdraw it, retain the exact pending_change.id that the customer confirmed removing:

await nozle.withdrawPendingSubscriptionChange(
  customerId,
  subscriptionId,
  confirmedPendingSubscriptionId,
  withdrawalActionKey,
)

The result is {subscription: {id, external_id, plan_code, status}, withdrawn_pending_subscription_id, replayed}. The same key returns the same body with replayed: true. The active plan is preserved. A new scheduled change while a change is pending replaces it with a new pending ID. A paid upgrade checkout is refused with 409 subscription_change_pending while a downgrade or cancellation is scheduled: withdraw the downgrade, or keep the subscription, first. Scheduling a change or cancelling at period end cancels an open upgrade checkout. Withdrawing the replaced ID returns 409 pending_subscription_changed. An unknown ID returns 404 pending_subscription_not_found.

Cancel at period end and Keep

Preview cancellation through the existing transition API:

const cancellation = await nozle.previewSubscriptionTransition({
  customerId, subscriptionId, operation: 'cancel', timing: 'end_of_period',
})

After displaying and confirming the ending date, apply it with its exact timestamp:

await nozle.applySubscriptionTransition({
  customerId, subscriptionId, operation: 'cancel', timing: 'end_of_period',
  expectedEffectiveAt: cancellation.subscription_transition.effective_at,
}, cancellationActionKey)

Keep reuses the existing uncancel operation with a separate confirmed action key:

await nozle.applySubscriptionTransition({
  customerId, subscriptionId, operation: 'uncancel',
}, keepActionKey)

Keep accepts no settlement overrides and is available only before the ending is due. Cancellation clears a pending downgrade; Keep does not recreate it. Do not reformat the preview timestamp before passing expectedEffectiveAt.

Scope payment recovery and verification

const scope = { customerId, subscriptionId }
const payment = await nozle.checkoutStatus(checkoutId, scope)
const verified = await nozle.verifyCheckout(checkoutId, razorpayVerification, scope)

razorpayVerification is the genuine browser callback containing razorpay_order_id, razorpay_payment_id, and razorpay_signature. verifyCheckout() posts these fields to the API; the SDK does not check the signature locally. Supply both scope fields when recovering a customer’s payment. Existing unscoped calls remain compatible, but do not provide the selected-customer/subscription constraint. An unknown checkout ID returns 404 checkout_session_not_found. Errors from checkoutStatus(), verifyCheckout() and checkoutInvoice() start with the method name, for example checkoutStatus failed: 404 Not Found. Before 0.10.0 they were labelled checkout failed: <status>; branch on NozleApiError status and code instead of the message. See errors. The status distinguishes awaiting_payment, processing, succeeded, failed, expired, and needs_review, with separate fulfillment_status. Reload the selected subscription before reporting activation. Reuse recoverable checkout IDs; do not start another collection for an uncertain payment. The merchant example maps SDK responses to React’s camelCase action types and persists retry context. Replace its demo login/file store with your application authentication and transactional storage for production workers. See the HTTP contract.

Entity subscriptions

Use Entity subscriptions when users, agents, projects, or workspaces under one paying customer can have different plans.

await nozle.entitySubscriptions.ensure('workspace_123', 'user_42')

const checkout = await nozle.entitySubscriptions.checkout(
  'workspace_123',
  'user_42',
  {
    planCode: 'pro_monthly',
    billingTime: 'anniversary',
    returnUrl: 'https://app.example.com/settings/billing',
    idempotencyKey: 'checkout-user-42-pro-v1',
  },
)

Change or cancel only that Entity:

await nozle.entitySubscriptions.changePlan('workspace_123', 'user_42', {
  planCode: 'max_annual',
  returnUrl: 'https://app.example.com/settings/billing',
  idempotencyKey: 'change-user-42-max-v1',
})

await nozle.entitySubscriptions.cancel('workspace_123', 'user_42', {
  timing: 'end_of_period',
  creditAction: 'none',
  idempotencyKey: 'cancel-user-42-v1',
})

Every method requires an sk_ key. See Entity Subscriptions for lifecycle and payment behavior.

billingTime accepts only calendar or anniversary.
Single Entity checkout also accepts free, trial, and pay-in-arrears plans. It returns completed with payment_source: "none".
changePlan() needs a transition policy for the plan pair and takes no billingTime. It returns scheduled or completed, plus external_entity_id and external_subscription_id.
cancel() on a pay-in-arrears plan without creditAction returns 422 with credit_action: not_supported_for_pay_in_arrears.
remove() on an Entity with billing history returns 403 entity_subscription_has_billing_history.
Entity subscriptions also return billing_authority and credit_import_completed_at, which the EntitySubscription type omits.

Buy several Entity plans together

checkoutMany() buys plans for several Entities with one payment. Do not loop over entitySubscriptions.checkout(): that creates separate invoices and payments.

const batch = await nozle.entitySubscriptions.checkoutMany('workspace_123', {
  items: [
    { externalEntityId: 'user_42', planCode: 'pro_monthly' },
    { externalEntityId: 'user_43', planCode: 'max_monthly' },
  ],
  billingTime: 'anniversary',
  returnUrl: 'https://app.example.com/settings/billing',
  idempotencyKey: 'seats-workspace-123-v1',
})

The result contains id, type (stripe, razorpay, processing, or completed), status (pending, open, completed, failed, or expired), client_secret, invoice_id, amount_cents, currency, replayed, expires_at, and items[] with external_entity_id, external_subscription_id, plan_code, and subscription_status. Razorpay results add the Razorpay fields.

Send 1 to 100 unique externalEntityId values. The SDK checks this before any request.
idempotencyKey is required, up to 255 bytes, and sent as the Idempotency-Key header. The same key and request returns replayed: true and reuses the open session. Replaying a failed or expired batch returns checkout_not_available.
The checkout expires after 23 hours.
Every plan must require up-front payment: pay in advance with an amount above 0 and no trial, or pay-in-advance fixed charges. Otherwise the whole batch fails with 422 validation_errors and error_details.items: ["paid_plan_required"]. Other item errors are mixed_currencies and mixed_intervals.
An untrusted returnUrl returns 422 with return_url: invalid_or_untrusted.
With no payment provider connected, the call returns 422 payment_provider_required, as single checkout does.

See bulk Entity checkout.

Settlement transitions

Preview and apply merchant-configurable cancellation, downgrade, and uncancel operations:

const params = {
  customerId: 'workspace_123',
  subscriptionId: 'subscription_123',
  operation: 'downgrade' as const,
  timing: 'end_of_period' as const,
  targetPlanCode: 'growth_monthly',
  creditAction: 'none' as const,
}

const preview = await nozle.previewSubscriptionTransition(params)

const transition = await nozle.applySubscriptionTransition(
  params,
  'transition-subscription-123-growth-v1',
)

Apply requires an idempotency key up to 255 bytes. These methods use the timing you pass even when the pair’s transition policy says otherwise; checkout always follows the policy. A downgrade on a pair whose policy direction is upgrade returns 422 target_plan_is_not_a_downgrade. See Subscriptions for settlement options and validation rules.

Customer creation

Create or update the customer before subscribing when needed:

const customer = await nozle.customers.upsert({
  externalId: 'workspace_123',
  name: 'Acme Workspace',
  email: 'billing@example.com',
})

See Customers and Entities for lifecycle methods.

Read usage

Requires @nozle-js/node 0.13.0.

const current = await nozle.currentUsage('cus_123')                  // this billing period
const past = await nozle.pastUsage('cus_123', { periods: 6 })         // newest first

Each period has from_datetime, to_datetime, currency, amount_cents, total_amount_cents and charges_usage (units and amount per charge and feature). Pass { subscriptionId } to read a specific subscription. Without a subscription ID, the customer’s one active subscription is used, and a customer with none or several gets an error. getSubscriptions(customerId) lists the customer’s active subscriptions from Core, so you can pick the external_id to pass as subscriptionId:

const subscriptions = await nozle.getSubscriptions('cus_123')
const usage = await nozle.currentUsage('cus_123', { subscriptionId: subscriptions[0].external_id })

Invoices

Requires @nozle-js/node 0.13.0.

const page = await nozle.invoices.list('cus_123', { status: 'finalized', page: 1 })   // { invoices, meta }
const invoice = await nozle.invoices.get(page.invoices[0].nozle_id)
const pdf = await nozle.invoices.downloadUrl(invoice.nozle_id)                        // string or null

invoices.list returns the newest invoices first and takes these options:

Option	Description
`status`	`draft`, `finalized`, `voided`, `failed` or `pending`.
`paymentStatus`	`pending`, `succeeded` or `failed`.
`paymentOverdue`	`true` keeps only unpaid invoices past their due date; `false` keeps the others.
`issuingDateFrom`, `issuingDateTo`	Inclusive issuing dates, `YYYY-MM-DD`.
`page`, `perPage`	Page number and page size.

const overdue = await nozle.invoices.list('cus_123', { paymentOverdue: true })

Pay an open invoice with checkoutInvoice. A PDF is generated the first time it is asked for, so the download call returns no URL until it exists; ask again a few seconds later, or wait for the invoice.generated webhook.

Alerts

Requires @nozle-js/node 0.13.0.

const subscription = { subscriptionId: 'sub_123' }
await nozle.alerts.create(subscription, {
  alertType: 'feature_current_usage_units',
  code: 'api_calls_80',
  featureCode: 'api_calls',
  thresholds: [{ value: 40000 }, { value: 10000, recurring: true }],
})
const { alerts } = await nozle.alerts.list(subscription)
await nozle.alerts.update(subscription, 'api_calls_80', { name: 'API calls at 80%' })
await nozle.alerts.delete(subscription, 'api_calls_80')

// Balance alerts belong to a wallet:
await nozle.alerts.create({ customerId: 'cus_123', walletCode: 'main' }, {
  alertType: 'wallet_credits_balance', code: 'low_credits', thresholds: [{ value: 100 }],
})

Usage alert types are current_usage_amount, feature_current_usage_amount and feature_current_usage_units (the feature_* ones need a feature code). Wallet alert types are wallet_balance_amount, wallet_credits_balance, wallet_ongoing_balance_amount and wallet_credits_ongoing_balance. Threshold values are cents, units or credits by type, and at most one threshold is recurring. Nozle sends the alert.triggered webhook when a threshold is crossed; verify it before acting.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Billing and subscriptions

List plans

Create checkout

Checkout errors

Manage a payment method

Direct subscription

Cancellation

Subscription self-service

Load eligible plans and preview a quote

Confirm a paid upgrade

Schedule or withdraw a downgrade

Cancel at period end and Keep

Scope payment recovery and verification

Entity subscriptions

Buy several Entity plans together

Settlement transitions

Customer creation

Read usage

Invoices

Alerts

​List plans

​Create checkout

​Checkout errors

​Manage a payment method

​Direct subscription

​Cancellation

​Subscription self-service

​Load eligible plans and preview a quote

​Confirm a paid upgrade

​Schedule or withdraw a downgrade

​Cancel at period end and Keep

​Scope payment recovery and verification

​Entity subscriptions

​Buy several Entity plans together

​Settlement transitions

​Customer creation

​Read usage

​Invoices

​Alerts

List plans

Create checkout

Checkout errors

Manage a payment method

Direct subscription

Cancellation

Subscription self-service

Load eligible plans and preview a quote

Confirm a paid upgrade

Schedule or withdraw a downgrade

Cancel at period end and Keep

Scope payment recovery and verification

Entity subscriptions

Buy several Entity plans together

Settlement transitions

Customer creation

Read usage

Invoices

Alerts