balance.depleted

{ "event": "balance.depleted", "timestamp": "2026-06-23T14:30:00.000Z", "organizationId": "8f14e45f-ceea-4e7a-9c3d-1c2b3a4d5e6f", "mode": "live", "apiVersion": "2026-08-27", "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.

Body

application/json

string

required

event

string

required

Allowed value: "balance.depleted"

timestamp

string

required

organizationId

string

required

mode

enum<string>

required

Available options:

live,

sandbox

apiVersion

string

required

data

object

required

Show child attributes

Response

200

Return any 2xx status code to acknowledge receipt of the event.

Overview

Events

balance.depleted

When this fires

Body

Response

​When this fires

Body

Response

When this fires