Credit balance low

Fired when the credit balance falls below one of the configured thresholds. Thresholds are configurable per customer, 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.