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 balance after depletion in rate scale. Zero, or negative when overage is allowed.

currencystring

The subscription currency.

{
  "event": "balance.depleted",
  "timestamp": "2026-06-22T17:45:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-06-10",
  "data": {
    "subscriptionId": "sub_1a2b3c4d",
    "customerId": "user_123",
    "currentBalance": 0,
    "currency": "usd"
  }
}

When this fires

The async usage processor fires this once when a deduction moves the prepaid balance from positive to zero or below. On plans that block on exhaustion, further usage is rejected with insufficient_balance; otherwise the balance goes negative and usage continues.

customer.state_changed fires alongside it with trigger balance_depleted.

Use it to cut off gated features or push an urgent top-up flow.