For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Paddle Docs home

usage_balance.depleted

Occurs when usage draws a customer's usage balance down to 0.

Join usage-based billing early access (beta)

Usage-based billing is in early access (beta). Read how it works, then apply to join. We'll reach out if you meet the program requirements.

Occurs when usage draws a customer's usage balance down to 0. Its balance.remaining.total is "0".

It occurs once when the balance runs out, not for each usage event after that. It doesn't occur when unused usage expires at the end of a billing period. It can occur again after the customer gets more usage from a renewal or a plan change, then runs out again.

During early access (beta), Paddle never blocks usage. After a usage balance runs out, Paddle keeps recording usage as overage, and you decide whether to keep providing the feature. Use this event to restrict access, let the customer know, or prompt them to upgrade. To learn more, see Set up usage-based billing.

Payload includes the complete usage balance entity. It doesn't include a subscription ID, so use customer_id and usage_balance_unit_id to match it to the customer and feature in your app.

event_idstringrequired
Example: evt_01gks14ge726w50ch2tmaw2a1x
Unique Paddle ID for this event, prefixed with evt_.
Pattern: ^evt_[a-z\d]{26}$
event_typestringrequired
Type of event sent by Paddle, in the format entity.event_type.
Values
+ Show all values
occurred_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this event occurred.
notification_idstringrequired
Example: ntf_01ghbkd0frb9k95cnhwd1bxpvk
Unique Paddle ID for this notification, prefixed with ntf_.
Pattern: ^ntf_[a-z\d]{26}$
dataobjectrequired
New or changed entity.
idstringrequired
Example: ubl_01h9zx4p8q2r5t7v9w1y3z5b7d
Unique Paddle ID for this usage balance entity, prefixed with ubl_.
Pattern: ^ubl_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of the customer this usage balance belongs to.
Pattern: ^ctm_[a-z\d]{26}$
usage_balance_unit_idstringrequired
Example: ubu_01kw8ta2j8x5t7q4v9m1kd6phz
Paddle ID of the usage balance unit that this usage balance is for. A customer has one usage balance for each usage balance unit, and usage events draw it down using the meters for that unit.
Pattern: ^ubu_[a-z\d]{26}$
balanceobjectrequired
Amounts for a customer's usage balance in the current billing period. Amounts are in the usage balance unit, not currency. The allowance isn't returned directly. To get it, add used.total and remaining.total.
usedobjectrequired
How much of the allowance the customer has used in the current billing period, broken down by source. Doesn't include overage.
totalstringrequired
Total across all sources, for example "1000" or "1000.5".
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
subscriptionstringrequired
Amount from allowances on the customer's subscriptions.
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
remainingobjectrequired
How much of the allowance is left in the current billing period, broken down by source. Counts down as usage is recorded and stops at "0", after which Paddle records usage in overage. During beta, Paddle never blocks usage, so restrict access to metered features in your app when remaining.total reaches "0".
totalstringrequired
Total across all sources, for example "1000" or "1000.5".
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
subscriptionstringrequired
Amount from allowances on the customer's subscriptions.
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
overageobjectrequired
Usage recorded after remaining reached "0" in the current billing period. Paddle doesn't bill for overage, and clears it when the subscription renews.
totalstringrequired
Total overage recorded in the current billing period, for example "0" or "25.5".
Max length: 45
Pattern: ^(0|[1-9][0-9]{0,34})(\.[0-9]{1,9})?$
started_atstring (date-time)
Example: 2024-10-12T07:20:50.52Z
When this usage balance first went into overage in the current billing period. Not returned when total is "0".
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
usage_balance.depleted
{
  "event_id": "evt_01js2n02s4fr6a8gvfm5enq0as",
  "event_type": "usage_balance.depleted",
  "occurred_at": "2026-09-27T16:42:10.283806Z",
  "notification_id": "ntf_01js2n03f91aw3v7q6f7x55r3z",
  "data": {
    "id": "ubl_01h9zx4p8q2r5t7v9w1y3z5b7d",
    "customer_id": "ctm_01gw9m680k848184fpttwr0b7z",
    "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
    "balance": {
      "used": {
        "total": "10000",
        "subscription": "10000"
      },
      "remaining": {
        "total": "0",
        "subscription": "0"
      },
      "overage": {
        "total": "0"
      }
    },
    "created_at": "2026-09-02T10:00:00Z",
    "updated_at": "2026-09-27T16:42:10Z"
  }
}

Was this page helpful?