Consume Credits

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" }
  }'

const res = await fetch("https://app.crovver.com/api/public/credits/consume", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tenantId: "workspace_123",
    poolKey: "api_calls",
    amount: 1,
    idempotencyKey: `consume-${Date.now()}`,
  }),
});
const { data } = await res.json();
if (data.result === "blocked") {
  // hard limit hit — surface upgrade prompt
}

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

{
  "success": true,
  "data": {
    "result": "blocked",
    "remaining": 0,
    "alreadyProcessed": false,
    "poolKey": "api_calls"
  }
}

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

{
  "success": false,
  "data": null,
  "error": {
    "message": "No active subscription found for this tenant",
    "code": "NO_SUBSCRIPTION"
  }
}

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

string

required

The external tenant ID from your application (e.g. workspace_123)

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.

integer

required

Number of credits to consume. Must be a positive integer.

string

required

Unique key for this consumption event. Duplicate calls with the same key return the original result — no double deduction.

string

Scope consumption to the tenant’s active subscription for this product (e.g. ats). A tenant holds at most one active subscription per product, so this is the recommended way to disambiguate multi-product tenants. Without it, the most recently created active subscription is used.

string

Scope consumption to an exact subscription ID. Takes effect together with productSlug if both are passed (they must refer to the same subscription).

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

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

integer

Credits remaining in the pool after this deduction.

boolean

true if this idempotencyKey was already processed. No deduction occurred on this call.

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" }
  }'

const res = await fetch("https://app.crovver.com/api/public/credits/consume", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tenantId: "workspace_123",
    poolKey: "api_calls",
    amount: 1,
    idempotencyKey: `consume-${Date.now()}`,
  }),
});
const { data } = await res.json();
if (data.result === "blocked") {
  // hard limit hit — surface upgrade prompt
}

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

{
  "success": true,
  "data": {
    "result": "blocked",
    "remaining": 0,
    "alreadyProcessed": false,
    "poolKey": "api_calls"
  }
}

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

{
  "success": false,
  "data": null,
  "error": {
    "message": "No active subscription found for this tenant",
    "code": "NO_SUBSCRIPTION"
  }
}

Get Credit BalanceFetch the current credit balance for all pools on a tenant's active subscription.

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" }
  }'

const res = await fetch("https://app.crovver.com/api/public/credits/consume", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tenantId: "workspace_123",
    poolKey: "api_calls",
    amount: 1,
    idempotencyKey: `consume-${Date.now()}`,
  }),
});
const { data } = await res.json();
if (data.result === "blocked") {
  // hard limit hit — surface upgrade prompt
}

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

{
  "success": true,
  "data": {
    "result": "blocked",
    "remaining": 0,
    "alreadyProcessed": false,
    "poolKey": "api_calls"
  }
}

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

{
  "success": false,
  "data": null,
  "error": {
    "message": "No active subscription found for this tenant",
    "code": "NO_SUBSCRIPTION"
  }
}

Overview

Subscriptions

Checkout

Credits

Add-ons

Capacity (Seats)

Features & Usage

Plans

Tenants

Deprecated

Consume Credits

Request Body

Authentication

Response

​Request Body

​Authentication

​Response

Request Body

Authentication

Response