Credit balance low

Fired when the credit balance falls below one of the configured thresholds. Thresholds are configured at the environment level, allowing you to set multiple alert levels (e.g., 80%, 50%, 20%). Useful for proactive low-balance notifications, in-app warnings, and auto top-up triggers.

WEBHOOK credit_balance.low

default

{
  "messageId": "b3093989-c6e7-429a-b13c-f90ffdf5ee48",
  "traceId": "e0ab6814-e858-411d-9482-03a26cdd03b3",
  "timestamp": "2026-01-21T14:46:52.006Z",
  "type": "credit_balance.low",
  "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": 4000,
  "remainingBalancePercentage": 80,
  "thresholdPercentage": 80,
  "consumedPercentage": 20,
  "eventId": "0506e820-98c9-4ffa-b4e0-748200a03dd9"
}

Body

application/json

type · enum<string> · required

Available options: credit_balance.low

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 crossed the threshold.

Show child attributes

creditCurrency · object · required

Credit currency (type) for which the balance is low.

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.

remainingBalancePercentage · number<double> · required

Remaining balance as a percentage of total granted (0–100).

thresholdPercentage · number<double> · required

The configured threshold percentage that was crossed (e.g., 80).

consumedPercentage · number<double> · required

How much of the total granted has been consumed (0–100).

traceId · string

Correlation ID for tracing.

eventId · string

Unique ID of the underlying event that triggered this webhook.