POST /v1/usage/consume
Usage consumption is for usage_pack entitlements such as credit packs, API call bundles, AI generation credits, or other unit-based products. Send the subject and the number of units to consume from your backend. The operation is atomic.
Keep metering server-side. The browser can request work, but your backend should decide whether access exists, run or accept the protected action, and then consume units with an idempotency key tied to that business event.
POST /v1/usage/consume
Authorization: Bearer lz_test_...
Idempotency-Key: usage-user_123-req_987
Content-Type: application/json
{
"subject_ref": "user_123",
"units": 100
}{
"ok": true,
"consumed": 100,
"usage_remaining": 900
}Recommended server-side flow
A practical usage flow starts with access and ends with consumption. That keeps paid work tied to the same entitlement state used by the rest of your Licenzy integration.
- Check access with
POST /v1/access/checkbefore starting protected work. - Reject or redirect the user if access is not allowed.
- Run, reserve, or accept the server-side work according to your product rules.
- Consume units with
POST /v1/usage/consumeusing an idempotency key for the business event. - Handle insufficient usage as a product state, not as a generic server failure.
Errors, retries and idempotency
Reuse the same Idempotency-Key when retrying the same business event. Licenzy uses idempotency to safely replay duplicate delivery of the same consumption request and to reject conflicting reuse.
HTTP 409 Conflict
{
"error": "insufficient_usage"
}409 Conflictwithinsufficient_usagemeans there are not enough units left.- Use one idempotency key per business event, not per HTTP attempt.
- Do not send a meter field. The confirmed request body is only
subject_refandunits.
insufficient_usage as a normal billing boundary. Your backend can return an upgrade, top-up, or checkout path instead of retrying the same consumption request with a different idempotency key.