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

# Entity Credit Transfers

> Allocate and return provenance-preserving paid top-up credits

**Auth:** secret key with `entity:write` when API permissions are enabled. Publishable keys are rejected.

Allocate paid customer top-up value:

```http theme={null}
POST /customers/workspace_123/entities/user_42/credit-allocations
Authorization: Bearer sk_...
Idempotency-Key: allocate-user-42-100
Content-Type: application/json

{
  "credit_system": "ai_credits",
  "amount": "100.000000000001"
}
```

Return unused allocated value:

```http theme={null}
POST /customers/workspace_123/entities/user_42/credit-deallocations
Authorization: Bearer sk_...
Idempotency-Key: deallocate-user-42-25
Content-Type: application/json

{
  "credit_system": "ai_credits",
  "amount": "25"
}
```

Amounts must be positive decimal strings with at most 12 fractional digits. Allocation can draw only from active paid customer top-ups. Deallocation returns unused value to each exact parent source; expiry, priority, payment provenance, and conservation remain enforced by PostgreSQL.

The API is available to authenticated secret-key callers and does not require a deployment allowlist. Tenant isolation, Entity status, Credit System configuration, source eligibility, and available balance are validated for every transfer.

Retry an uncertain response with the same idempotency key and identical payload. Reusing a key with a different customer, Entity, Credit System, direction, or amount returns a conflict.