Payload

All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.

subscriptionIdstring

The subscription ID.

customerIdstring

The customer ID. Returns your externalId if you provided one when creating the customer, otherwise returns the Commet publicId.

currentBalancenumber

The remaining balance in rate scale (10000 = $1.00 of the subscription currency).

thresholdBalancenumber

The low-balance threshold that was crossed: 10% of the last refill, in rate scale.

currencystring

The subscription currency.

{
  "event": "balance.low",
  "timestamp": "2026-06-18T09:12:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-06-10",
  "data": {
    "subscriptionId": "sub_1a2b3c4d",
    "customerId": "user_123",
    "currentBalance": 90000,
    "thresholdBalance": 100000,
    "currency": "usd"
  }
}

When this fires

The async usage processor watches every balance deduction. When a batch moves the prepaid balance from above to at-or-below 10% of the last refill (period reset, top-up, or manual adjustment), this event fires once per crossing. A top-up re-arms it.

Amounts are in rate scale (10000 = $1.00) in the subscription currency.

Use it to prompt the customer to top up before usage gets blocked.