Customers and Entities

Customers represent the merchant’s billable account or workspace. Entities represent children of that customer, such as users, agents, projects, or environments.

Upsert a customer

customers.upsert() sends the merchant’s secret key directly to Nozle Core. Core derives the owning organization from that key; the SDK never provisions a customer through a global or master organization.

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

Field	Type	Required	Description
`externalId`	`string`	yes	Stable application-owned customer identifier.
`name`	`string`	no	Display name.
`email`	`string`	no	Billing or contact email.
`billingConfiguration`	`CustomerBillingConfiguration`	no	Payment provider assignment. Requires Node.js `0.12.0`.

Link a customer that already exists in Stripe

Pass billingConfiguration with the Stripe customer ID to link it in the same call. Nozle stores the link and does not create a new Stripe customer. Sending the same upsert again is safe.

await nozle.customers.upsert({
  externalId: 'workspace_123',
  name: 'Acme Workspace',
  billingConfiguration: {
    paymentProvider: 'stripe',
    paymentProviderCode: 'stripe_main',
    providerCustomerId: 'cus_ABC123',
  },
})

Field	Type	Required	Description
`paymentProvider`	`string`	yes	Provider type, such as `stripe`.
`paymentProviderCode`	`string`	no	Code of the provider connection in Nozle.
`providerCustomerId`	`string`	no	Existing customer ID at the provider, such as `cus_…`.
`syncWithProvider`	`boolean`	no	Create the customer at the provider when no `providerCustomerId` is given.
`providerPaymentMethods`	`string[]`	no	Payment methods the customer may use. Defaults to `card`.

Nozle keeps the assignment with or without syncWithProvider, and checkout charges only through the assigned connection. See Assign the connection to customers.

Read Entities

const entity = await nozle.entities.get('workspace_123', 'user_42')

const page = await nozle.entities.list('workspace_123', {
  status: 'active',
  limit: 50,
})

const nextPage = page.next_cursor
  ? await nozle.entities.list('workspace_123', {
      status: 'active',
      limit: 50,
      cursor: page.next_cursor,
    })
  : null

status accepts active, suspended, or deleted. limit must be an integer from 1 to 100.

Upsert an Entity

const result = await nozle.entities.upsert(
  'workspace_123',
  'user_42',
  {
    name: 'Asha',
    status: 'active',
    metadata: { role: 'agent' },
  },
  { idempotencyKey: 'entity-user-42-v1' },
)

console.log(result.action)
console.log(result.replayed)

Entity IDs and idempotency keys are limited to 255 UTF-8 bytes. Retry an uncertain mutation with the same key and payload.

Activate or suspend

await nozle.entities.suspend('workspace_123', 'user_42', {
  idempotencyKey: 'suspend-user-42-v1',
})

await nozle.entities.activate('workspace_123', 'user_42', {
  idempotencyKey: 'activate-user-42-v2',
})

These helpers first fetch the Entity, then preserve its current name and metadata while changing status.

Bulk upsert

const result = await nozle.entities.bulkUpsert(
  'workspace_123',
  [
    { externalId: 'user_42', name: 'Asha', status: 'active' },
    { externalId: 'user_43', name: 'Ravi', status: 'suspended' },
  ],
  { idempotencyKey: 'workspace-123-users-import-7' },
)

console.log(result.counts)

Each bulk request must contain 1–500 unique Entity external IDs.

Seat billing is explicit

Entity lifecycle methods do not emit billable seat events. If seats are billed through a Feature, track add/remove operations separately with stable transaction IDs through nozle.track().

await nozle.track(
  'workspace_123',
  'billable_seats',
  { user_id: 'user_42', operation: 'add' },
  {
    subscriptionId: 'workspace_123_subscription',
    transactionId: 'seat-add-user-42-v1',
  },
)

Entity credits

Use Entity IDs with nozle.credits and nozle.usage for per-Entity balances, transfers, attribution, and pool policy. See Product credits.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Customers and Entities

Upsert a customer

Link a customer that already exists in Stripe

Read Entities

Upsert an Entity

Activate or suspend

Bulk upsert

Seat billing is explicit

Entity credits

​Upsert a customer

​Link a customer that already exists in Stripe

​Read Entities

​Upsert an Entity

​Activate or suspend

​Bulk upsert

​Seat billing is explicit

​Entity credits

Upsert a customer

Link a customer that already exists in Stripe

Read Entities

Upsert an Entity

Activate or suspend

Bulk upsert

Seat billing is explicit

Entity credits