Skip to main content
Entities are stable customer-owned subjects such as users, seats, agents, or projects. They add a scoped credit pool without replacing the customer pool.
An Entity belongs to exactly one customer and organization. Recreating an Entity with the same external ID produces a different incarnation; financial history remains bound to the original durable Entity UUID.

​
Pool policies

Each active plan can select one policy per Credit System:
  • entity_only spends only Entity-owned sources;
  • entity_then_customer spends Entity sources first, then the shared customer pool;
  • customer_only records Entity attribution while spending only shared customer sources.
The balance API returns all three exact-decimal views:
effective_available is zero for an inactive Entity or when no unambiguous active plan policy exists. The API never infers a fallback policy from available sources.

​
Sources and transfers

Entity plan grants and allocated paid top-ups remain separate sources. Allocation moves value from a customer paid-top-up source into an allocated_top_up child while preserving its parent source, payment provenance, priority, and expiry. Only unused allocated top-up value can be returned. Subscription grants are never presented as transferable company value. Paid top-ups initially belong to the customer pool. They are not assigned automatically to the Entity that initiated checkout or to the first paid Entity. Your backend can:
  • leave the credits in the customer pool for a plan that allows shared-pool spending;
  • allocate an exact amount to one Entity; or
  • split the purchase across multiple Entities.
For example, a 250-credit top-up can allocate 100 credits to user_42, 100 to support_bot, and leave 50 in the customer pool. Each allocation remains linked to the exact paid parent source.
Allocation and deallocation are backend-only mutations. They require a secret credential, an idempotency key, and eligible paid top-up sources.
Keep amounts as decimal strings throughout your application. Do not convert them to JavaScript numbers or binary floating-point values.

​
Lifecycle

Entities can be active, suspended, or deleted.
  • Active Entities can read and spend according to their pool policy.
  • Suspension or deletion blocks new usage, expires unused Entity subscription grants, and returns unused allocated top-ups to their original parents.
  • Operations, allocations, source provenance, and status history remain immutable.
  • Reactivation does not reuse an older incarnation’s idempotency results or mint duplicate period grants.

​
Seat billing

Entities and billable seats are separate contracts. Creating, suspending, reactivating, or deleting an Entity never changes billed usage. Entity subscriptions are also separate from credit pools and seat metrics. Use an Entity subscription only when that Entity owns an independent plan. Credit allocation still follows the configured pool policy, while seat billing still follows explicit usage events. An Entity-owned subscription grant is materialized only for that subscription’s owning Entity. A Pro Entity receives the Pro grant and a Max Entity receives the Max grant; Nozle does not copy every active Entity plan grant to every Entity under the customer. If your product bills per seat, configure a recurring unique-count Billable Metric:
Your authenticated backend sends explicit add and remove events with a stable user ID and a unique transaction ID for each business transition. The same external ID may be used for both an Entity and a seat, but neither API automatically calls the other.
Removal uses a new transaction ID, the same user_id, and "operation_type": "remove". Nozle rejects a reused transaction ID and does not create a second usage effect.

​
Dashboard

The customer Entities tab provides:
  • active, suspended, and deleted Entity filters;
  • create/edit, bulk upsert, activation, and suspension flows;
  • plan, allocated top-up, shared, consumed, and effective balances;
  • source provenance and expiry;
  • immutable Entity operation history;
  • allocation/deallocation previews and confirmations.
All mutation retries preserve their idempotency key until the result is known. Changing the payload starts a new key.

​
Integration sequence

  1. Create or bulk-upsert stable Entity IDs from your backend.
  2. Configure per-Entity grant rules and one pool policy per plan/Credit System.
  3. Read Entity balances before enabling mutation traffic.
  4. Test transfers with a sandbox customer and Credit System.
  5. Track usage with both customer_id and entity_id after the sandbox results are accepted.
  6. If applicable, send seat events independently from your backend and verify current usage.
  7. Run the acceptance audit before enabling shared fallback or broader traffic.

Entity API

Entity subscriptions

Entity balances

Node SDK

React components