Skip to main content
POST
Entity Credit Transfers
Base URL: https://api.nozle.app/engine/api/v1. Auth: secret key with entity:write. Publishable keys are rejected. Allocate paid customer top-up value:
Return unused allocated value:
Amounts must be positive decimal strings with at most 18 integer digits and 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. 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 409 idempotency_key_reused.

Response

A completed allocation returns 201, including a replay. A completed deallocation returns 200. The body has transferred, operation_id, customer_id, entity_id, credit_system, direction, amount, available, parent_sources, entity_sources, and replayed. Each source leg has source_id, source_type, scope, amount, before, after, and expires_at. When there is not enough eligible value, the response is 422 with the same body, transferred: false, and a reason: insufficient_customer_top_up_credits for an allocation, or insufficient_entity_allocated_credits for a deallocation.

Error handling

If a request returns HTTP 403 with credit_transfer_not_enabled, contact support with the request ID to check the transfer configuration. Do not retry it as a transient network failure or report the transfer as successful.