Skip to main content
POST
/
api
/
public
/
credits
/
consume
curl -X POST "https://app.crovver.com/api/public/credits/consume" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "workspace_123",
    "poolKey": "api_calls",
    "amount": 1,
    "idempotencyKey": "consume-1778423112701",
    "metadata": { "endpoint": "/api/export" }
  }'

{
  "success": true,
  "data": {
    "result": "allowed",
    "remaining": 849,
    "alreadyProcessed": false,
    "poolKey": "api_calls"
  }
}
Deducts credits from a tenant’s pool. Credits are deducted FIFO — base credits first, then add-on credits, earliest-expiry first. Passing the same idempotencyKey twice returns the original result without double-deducting.

​
Request Body

​
tenantId
string
required
The external tenant ID from your application (e.g. workspace_123)
​
poolKey
string
required
The credit pool to deduct from (e.g. api_calls, ai_tokens). Must match a pool defined on the tenant’s active plan.
​
amount
integer
required
Number of credits to consume. Must be a positive integer.
​
idempotencyKey
string
required
Unique key for this consumption event. Duplicate calls with the same key return the original result — no double deduction.
​
metadata
object
Optional context stored on the event for auditing (e.g. { "endpoint": "/api/export", "userId": "u_123" }).

​
Authentication

Requires a secret key (Authorization: Bearer sk_live_...) or service key (x-service-key).

​
Response

​
data.result
string
Outcome: allowed, warning, or blocked.
  • allowed — credits deducted successfully
  • warning — credits deducted but balance is now below zero (soft limit pool)
  • blocked — insufficient credits on a hard limit pool; no deduction occurred
​
data.remaining
integer
Credits remaining in the pool after this deduction.
​
data.alreadyProcessed
boolean
true if this idempotencyKey was already processed. No deduction occurred on this call.
​
data.poolKey
string
The pool key that was targeted.
curl -X POST "https://app.crovver.com/api/public/credits/consume" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "workspace_123",
    "poolKey": "api_calls",
    "amount": 1,
    "idempotencyKey": "consume-1778423112701",
    "metadata": { "endpoint": "/api/export" }
  }'

{
  "success": true,
  "data": {
    "result": "allowed",
    "remaining": 849,
    "alreadyProcessed": false,
    "poolKey": "api_calls"
  }
}