Skip to main content
POST
Check & Deduct Credits
Base URL: https://api.nozle.app/engine/api/v1.
Deprecated. Use Track and Consume Credits (POST /usage/track) instead. This is a legacy wallet adapter. It does not apply Feature conversion rates or the product-credit source ledger. New integrations must use Track and Consume Credits.Responses carry Deprecation: true and Link: </api/v1/usage/track>; rel="successor-version". The endpoint still works.
Check whether a customer’s wallet has enough credits and deduct them. The Engine locks the customer’s newest active wallet for the check-and-deduct calls, so concurrent calls cannot overspend it, then spends the credits through Core’s wallet transaction API (POST /wallet_transactions with voided_credits). Core records a voided outbound wallet transaction, updates the wallet’s balances, sends wallet.updated and wallet_transaction.created and runs wallet alerts.
Not idempotent. Every call that returns allowed: true deducts, and a retry after a timeout or a 5xx can deduct again. An Idempotency-Key header is ignored. For usage you may retry, use Track and Consume Credits, which requires an Idempotency-Key.
Auth: sk_ only. Publishable keys are rejected with 403. With API key permissions, the key needs credit_system:write and wallet_transaction:write; without either the call returns 403 with code: permission_denied before any deduction.
string
required
External customer ID
number
required
Number of credits to deduct (must be positive)
boolean
required
Whether sufficient balance existed to fulfill the deduction
number
required
The wallet’s credits_balance after the deduction. When allowed is false it is the current balance, unchanged.
When allowed is false, no credits are deducted and no wallet transaction is written. The request still returns 200, so check allowed rather than the status code. A request that asks for exactly the remaining balance is allowed and leaves remaining at 0.
Earlier versions of this endpoint took a feature field. It was never used. You can still send it: an old value is ignored and has no effect.

Example

Errors

The deducted amount is credits × the wallet’s rate, rounded to the wallet currency. The deduction lowers credits_balance and the ongoing credit balance by credits, lowers balance_cents and the ongoing balance by that amount, and adds both to the consumed credits and consumed amount. Core records a voided outbound wallet transaction with the money amount and the credits. See Credit balance.