> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Product credits

> Discover credit systems, read exact balances, transfer Entity credits, and atomically consume usage.

Product-credit values are exact decimal strings. Do not convert balances, transfer amounts, or deductions to JavaScript `number` when precision matters.

## List credit systems

```ts theme={null}
const systems = await nozle.creditSystems.list()

for (const system of systems) {
  console.log(system.code, system.unitName, system.status)
}
```

`list()` fetches every active page and returns normalized camel-case `CreditSystem` objects.

## Customer balances

```ts theme={null}
const balance = await nozle.credits.getBalance(
  'workspace_123',
  'ai_credits',
)

console.log(balance.available) // exact decimal string
console.log(balance.sources)

const allBalances = await nozle.credits.listBalances('workspace_123')
```

`CreditBalance` includes credit-system metadata, `available`, an `as_of` timestamp, and ordered balance sources. Sources identify their type, initial and remaining amounts, validity window, priority, scope, and transfer flags.

## Customer operation history

```ts theme={null}
const page = await nozle.credits.listOperations('workspace_123', {
  creditSystemCode: 'ai_credits',
  limit: 25,
})

const nextPage = page.next_cursor
  ? await nozle.credits.listOperations('workspace_123', {
      creditSystemCode: 'ai_credits',
      limit: 25,
      cursor: page.next_cursor,
    })
  : null
```

`limit` must be an integer from 1 to 100. Operations expose exact credit amounts, status, reason, rate snapshot, event time, and source allocations.

## Entity balances

```ts theme={null}
const balance = await nozle.credits.getEntityBalance(
  'workspace_123',
  'user_42',
  'ai_credits',
)

console.log(balance.entity_available)
console.log(balance.shared_available)
console.log(balance.effective_available)
console.log(balance.pool_policy)

const allBalances = await nozle.credits.listEntityBalances(
  'workspace_123',
  'user_42',
)
```

`pool_policy` is `entity_only`, `entity_then_customer`, `customer_only`, or `null` when no policy applies.

## Entity operation history

```ts theme={null}
const history = await nozle.credits.listEntityOperations(
  'workspace_123',
  'user_42',
  {
    creditSystemCode: 'ai_credits',
    limit: 25,
  },
)
```

## Allocate credits

Transfers require a secret key, a positive decimal string with at most 12 decimal places, and an idempotency key.

```ts theme={null}
const allocation = await nozle.credits.allocate(
  'workspace_123',
  'user_42',
  {
    creditSystemCode: 'ai_credits',
    amount: '100.000000000001',
  },
  { idempotencyKey: 'allocate-user-42-100-v1' },
)

console.log(allocation.transferred)
console.log(allocation.parent_sources)
console.log(allocation.entity_sources)
console.log(allocation.replayed)
```

## Deallocate credits

```ts theme={null}
const deallocation = await nozle.credits.deallocate(
  'workspace_123',
  'user_42',
  {
    creditSystemCode: 'ai_credits',
    amount: '25',
  },
  { idempotencyKey: 'deallocate-user-42-25-v1' },
)
```

Transfers are subject to Nozle's exact transfer policy and source eligibility rules. Retry an uncertain transfer with the same key and payload.

## Advisory usage check

```ts theme={null}
const check = await nozle.usage.check({
  customerId: 'workspace_123',
  entityId: 'user_42',
  featureCode: 'agent_execution',
  creditSystemCode: 'ai_credits',
  properties: { model: 'example-model' },
  occurredAt: new Date().toISOString(),
})

console.log(check.advisory) // true
console.log(check.allowed)
console.log(check.credits_required)
console.log(check.projected_remaining)
console.log(check.projected_deductions)
```

`usage.check()` does not reserve or mutate credits. Another request can spend the projected sources before a later consume request.

## Atomic usage tracking

```ts theme={null}
const result = await nozle.usage.track(
  {
    customerId: 'workspace_123',
    entityId: 'user_42',
    featureCode: 'agent_execution',
    creditSystemCode: 'ai_credits',
    properties: { model: 'example-model' },
    timestamp: new Date().toISOString(),
  },
  { idempotencyKey: 'agent-execution-0183f' },
)

if (!result.allowed) {
  console.log(result.reason, result.available)
}
```

`usage.track()` atomically evaluates the metric conversion, selects eligible sources, deducts credits, and records the operation. The optional Entity ID enables Entity attribution and configured pool policy.

## Legacy wallet adapter

`nozle.checkAndDeduct({ customerId, feature, credits })` remains available for the legacy wallet path. New product-credit integrations should use `usage.check()` and `usage.track()`.

## Security

Keep credit reads and all mutations behind authenticated backend routes. Derive customer and Entity IDs from server-owned identity data and return only fields the browser needs.