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)
}

Each Plan contains code, name, amount_cents, amount_currency, and interval.

Create checkout

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

checkout() requires an sk_ key and may return:

type CheckoutResult =
  | {
      type: 'stripe'
      url?: string
      client_secret?: string
      clientSecret?: string
      invoice_id?: string
      amount_cents?: number
      currency?: string
    }
  | {
      type: 'completed' | 'scheduled'
      status: string
      subscription_id?: string
      plan_code?: string
    }

Handle every result shape explicitly:

if (result.type === 'stripe') {
  if (result.url) return redirect(result.url)
  if (result.client_secret || result.clientSecret) {
    return { clientSecret: result.client_secret ?? result.clientSecret }
  }
  throw new Error('Stripe checkout returned no URL or client secret')
}

if (result.type === 'completed') {
  return { status: result.status, refreshBilling: true }
}

return { status: result.status, scheduled: true }

Validate the exact HTTPS return origin on your server before passing it to Nozle.

Stripe webhook processing is authoritative. A checkout result, browser redirect, or client callback does not by itself prove that a paid subscription is active.

Direct subscription

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. Use checkout for payment-gated plan changes; use direct subscription only where your configured product flow does not require an interactive payment.

Cancellation

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

The policy defaults to end_of_period and also accepts immediate.

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',
  idempotencyKey: 'cancel-user-42-v1',
})

Every method requires an sk_ key. See Entity Subscriptions for lifecycle and payment behavior. The Node.js SDK currently exposes single-Entity checkout and plan changes. For a mixed seat-pool purchase, call the bulk Entity checkout endpoint from the same trusted backend and return only the Stripe result to your browser. Do not loop over entitySubscriptions.checkout(): that would create separate invoices and payments.

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. 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.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Billing and subscriptions

List plans

Create checkout

Direct subscription

Cancellation

Entity subscriptions

Settlement transitions

Customer creation

​List plans

​Create checkout

​Direct subscription

​Cancellation

​Entity subscriptions

​Settlement transitions

​Customer creation

List plans

Create checkout

Direct subscription

Cancellation

Entity subscriptions

Settlement transitions

Customer creation