Credit balance depleted

Fired when the credit balance reaches zero. Use to halt consumption, enforce hard limits, or prompt a top-up flow.

WEBHOOK credit_balance.depleted

default

{
  "messageId": "c4093989-d7e7-429a-b13c-f90ffdf5ee49",
  "traceId": "f1ab6814-e858-411d-9482-03a26cdd03b4",
  "timestamp": "2026-01-21T15:30:00.000Z",
  "type": "credit_balance.depleted",
  "customer": {
    "id": "customer-b2b94b",
    "name": "Acme Corp",
    "billingId": "cus_Tpi55JrRDSuEvs"
  },
  "creditCurrency": {
    "id": "cred-type-ai-tokens",
    "name": "AI Tokens",
    "description": "Tokens used for AI features",
    "unitLabel": {
      "singular": "token",
      "plural": "tokens"
    }
  },
  "totalGranted": 5000,
  "remainingBalance": 0,
  "consumedPercentage": 100,
  "eventId": "1617e820-98c9-4ffa-b4e0-748200a03dd0"
}

Body

application/json

type · enum<string> · required

Available options: credit_balance.depleted

messageId · string · required

Unique webhook message ID for idempotency.

timestamp · string<date-time> · required

Time the event was generated.

customer · object · required

Customer whose credit balance was depleted.

Show child attributes

creditCurrency · object · required

Credit currency (type) that was depleted.

Show child attributes

totalGranted · number<double> · required

Sum of all grants in the pool at event time.

remainingBalance · number<double> · required

Remaining balance at event time (will be 0 at depletion).

traceId · string

Correlation ID for tracing.

eventId · string

Unique ID of the underlying event that triggered this webhook.

consumedPercentage · number<double>

How much of the total granted has been consumed (will be 100 at depletion).