> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# usage_balance.depleted

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

---

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](https://developer.paddle.com/build/usage-based-billing.md).

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.
> **Early access (beta): usage-based billing**

## Schema

```json
{
  "type": "object",
  "required": [
    "event_id",
    "event_type",
    "occurred_at",
    "notification_id",
    "data"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "pattern": "^evt_[a-z\\d]{26}$",
      "description": "Unique Paddle ID for this event, prefixed with `evt_`.",
      "title": "Event ID",
      "examples": [
        "evt_01gks14ge726w50ch2tmaw2a1x"
      ]
    },
    "event_type": {
      "type": "string",
      "enum": [
        "address.created",
        "address.imported",
        "address.updated",
        "adjustment.created",
        "adjustment.updated",
        "api_key.created",
        "api_key.expired",
        "api_key.expiring",
        "api_key.revoked",
        "api_key.updated",
        "api_key_exposure.created",
        "business.created",
        "business.imported",
        "business.updated",
        "client_token.created",
        "client_token.revoked",
        "client_token.updated",
        "customer.created",
        "customer.imported",
        "customer.updated",
        "discount.created",
        "discount.imported",
        "discount.updated",
        "discount_group.created",
        "discount_group.updated",
        "meter.created",
        "meter.updated",
        "payment_method.saved",
        "payment_method.deleted",
        "payout.created",
        "payout.paid",
        "price.created",
        "price.imported",
        "price.updated",
        "product.created",
        "product.imported",
        "product.updated",
        "report.created",
        "report.updated",
        "subscription.activated",
        "subscription.canceled",
        "subscription.created",
        "subscription.imported",
        "subscription.past_due",
        "subscription.paused",
        "subscription.resumed",
        "subscription.trialing",
        "subscription.updated",
        "transaction.billed",
        "transaction.canceled",
        "transaction.completed",
        "transaction.created",
        "transaction.paid",
        "transaction.past_due",
        "transaction.payment_failed",
        "transaction.ready",
        "transaction.revised",
        "transaction.updated",
        "usage_balance.depleted"
      ],
      "description": "Type of event sent by Paddle, in the format `entity.event_type`.",
      "title": "Event type name",
      "x-enum-descriptions": {
        "address.created": {
          "description": "An [`address.created`](https://developer.paddle.com/webhooks/addresses/address-created) event."
        },
        "address.imported": {
          "description": "An [`address.imported`](https://developer.paddle.com/webhooks/addresses/address-imported) event."
        },
        "address.updated": {
          "description": "An [`address.updated`](https://developer.paddle.com/webhooks/addresses/address-updated) event."
        },
        "adjustment.created": {
          "description": "An [`adjustment.created`](https://developer.paddle.com/webhooks/adjustments/adjustment-created) event."
        },
        "adjustment.updated": {
          "description": "An [`adjustment.updated`](https://developer.paddle.com/webhooks/adjustments/adjustment-updated) event."
        },
        "api_key.created": {
          "description": "An [`api_key.created`](https://developer.paddle.com/webhooks/api-keys/api-key-created) event."
        },
        "api_key.expired": {
          "description": "An [`api_key.expired`](https://developer.paddle.com/webhooks/api-keys/api-key-expired) event."
        },
        "api_key.expiring": {
          "description": "An [`api_key.expiring`](https://developer.paddle.com/webhooks/api-keys/api-key-expiring) event."
        },
        "api_key.revoked": {
          "description": "An [`api_key.revoked`](https://developer.paddle.com/webhooks/api-keys/api-key-revoked) event."
        },
        "api_key.updated": {
          "description": "An [`api_key.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-updated) event."
        },
        "api_key_exposure.created": {
          "description": "An [`api_key_exposure.created`](https://developer.paddle.com/webhooks/api-key-exposures/api-key-exposure-created) event."
        },
        "business.created": {
          "description": "A [`business.created`](https://developer.paddle.com/webhooks/businesses/business-created) event."
        },
        "business.imported": {
          "description": "A [`business.imported`](https://developer.paddle.com/webhooks/businesses/business-imported) event."
        },
        "business.updated": {
          "description": "A [`business.updated`](https://developer.paddle.com/webhooks/businesses/business-updated) event."
        },
        "client_token.created": {
          "description": "A [`client_token.created`](https://developer.paddle.com/webhooks/client-tokens/client-token-created) event."
        },
        "client_token.revoked": {
          "description": "A [`client_token.revoked`](https://developer.paddle.com/webhooks/client-tokens/client-token-revoked) event."
        },
        "client_token.updated": {
          "description": "A [`client_token.updated`](https://developer.paddle.com/webhooks/client-tokens/client-token-updated) event."
        },
        "customer.created": {
          "description": "A [`customer.created`](https://developer.paddle.com/webhooks/customers/customer-created) event."
        },
        "customer.imported": {
          "description": "A [`customer.imported`](https://developer.paddle.com/webhooks/customers/customer-imported) event."
        },
        "customer.updated": {
          "description": "A [`customer.updated`](https://developer.paddle.com/webhooks/customers/customer-updated) event."
        },
        "discount.created": {
          "description": "A [`discount.created`](https://developer.paddle.com/webhooks/discounts/discount-created) event."
        },
        "discount.imported": {
          "description": "A [`discount.imported`](https://developer.paddle.com/webhooks/discounts/discount-imported) event."
        },
        "discount.updated": {
          "description": "A [`discount.updated`](https://developer.paddle.com/webhooks/discounts/discount-updated) event."
        },
        "discount_group.created": {
          "description": "A [`discount_group.created`](https://developer.paddle.com/webhooks/discount-groups/discount-group-created) event."
        },
        "discount_group.updated": {
          "description": "A [`discount_group.updated`](https://developer.paddle.com/webhooks/discount-groups/discount-group-updated) event."
        },
        "meter.created": {
          "description": "A [`meter.created`](https://developer.paddle.com/webhooks/meters/meter-created) event."
        },
        "meter.updated": {
          "description": "A [`meter.updated`](https://developer.paddle.com/webhooks/meters/meter-updated) event."
        },
        "payment_method.saved": {
          "description": "A [`payment_method.saved`](https://developer.paddle.com/webhooks/payment-methods/payment-method-saved) event."
        },
        "payment_method.deleted": {
          "description": "A [`payment_method.deleted`](https://developer.paddle.com/webhooks/payment-methods/payment-method-deleted) event."
        },
        "payout.created": {
          "description": "A [`payout.created`](https://developer.paddle.com/webhooks/payouts/payout-created) event."
        },
        "payout.paid": {
          "description": "A [`payout.paid`](https://developer.paddle.com/webhooks/payouts/payout-paid) event."
        },
        "price.created": {
          "description": "A [`price.created`](https://developer.paddle.com/webhooks/prices/price-created) event."
        },
        "price.imported": {
          "description": "A [`price.imported`](https://developer.paddle.com/webhooks/prices/price-imported) event."
        },
        "price.updated": {
          "description": "A [`price.updated`](https://developer.paddle.com/webhooks/prices/price-updated) event."
        },
        "product.created": {
          "description": "A [`product.created`](https://developer.paddle.com/webhooks/products/product-created) event."
        },
        "product.imported": {
          "description": "A [`product.imported`](https://developer.paddle.com/webhooks/products/product-imported) event."
        },
        "product.updated": {
          "description": "A [`product.updated`](https://developer.paddle.com/webhooks/products/product-updated) event."
        },
        "report.created": {
          "description": "A [`report.created`](https://developer.paddle.com/webhooks/reports/report-created) event."
        },
        "report.updated": {
          "description": "A [`report.updated`](https://developer.paddle.com/webhooks/reports/report-updated) event."
        },
        "subscription.activated": {
          "description": "A [`subscription.activated`](https://developer.paddle.com/webhooks/subscriptions/subscription-activated) event."
        },
        "subscription.canceled": {
          "description": "A [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled) event."
        },
        "subscription.created": {
          "description": "A [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created) event."
        },
        "subscription.imported": {
          "description": "A [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported) event."
        },
        "subscription.past_due": {
          "description": "A [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due) event."
        },
        "subscription.paused": {
          "description": "A [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused) event."
        },
        "subscription.resumed": {
          "description": "A [`subscription.resumed`](https://developer.paddle.com/webhooks/subscriptions/subscription-resumed) event."
        },
        "subscription.trialing": {
          "description": "A [`subscription.trialing`](https://developer.paddle.com/webhooks/subscriptions/subscription-trialing) event."
        },
        "subscription.updated": {
          "description": "A [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated) event."
        },
        "transaction.billed": {
          "description": "A [`transaction.billed`](https://developer.paddle.com/webhooks/transactions/transaction-billed) event."
        },
        "transaction.canceled": {
          "description": "A [`transaction.canceled`](https://developer.paddle.com/webhooks/transactions/transaction-canceled) event."
        },
        "transaction.completed": {
          "description": "A [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed) event."
        },
        "transaction.created": {
          "description": "A [`transaction.created`](https://developer.paddle.com/webhooks/transactions/transaction-created) event."
        },
        "transaction.paid": {
          "description": "A [`transaction.paid`](https://developer.paddle.com/webhooks/transactions/transaction-paid) event."
        },
        "transaction.past_due": {
          "description": "A [`transaction.past_due`](https://developer.paddle.com/webhooks/transactions/transaction-past-due) event."
        },
        "transaction.payment_failed": {
          "description": "A [`transaction.payment_failed`](https://developer.paddle.com/webhooks/transactions/transaction-payment-failed) event."
        },
        "transaction.ready": {
          "description": "A [`transaction.ready`](https://developer.paddle.com/webhooks/transactions/transaction-ready) event."
        },
        "transaction.revised": {
          "description": "A [`transaction.revised`](https://developer.paddle.com/webhooks/transactions/transaction-revised) event."
        },
        "transaction.updated": {
          "description": "A [`transaction.updated`](https://developer.paddle.com/webhooks/transactions/transaction-updated) event."
        },
        "usage_balance.depleted": {
          "description": "A [`usage_balance.depleted`](https://developer.paddle.com/webhooks/usage-balances/usage-balance-depleted) event."
        }
      }
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 datetime string of when this event occurred.",
      "title": "Timestamp",
      "examples": [
        "2024-10-12T07:20:50.52Z"
      ]
    },
    "notification_id": {
      "type": "string",
      "pattern": "^ntf_[a-z\\d]{26}$",
      "description": "Unique Paddle ID for this notification, prefixed with `ntf_`.",
      "title": "Notification ID",
      "examples": [
        "ntf_01ghbkd0frb9k95cnhwd1bxpvk"
      ]
    },
    "data": {
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^ubl_[a-z\\d]{26}$",
          "description": "Unique Paddle ID for this usage balance entity, prefixed with `ubl_`.",
          "title": "Usage Balance ID",
          "examples": [
            "ubl_01h9zx4p8q2r5t7v9w1y3z5b7d"
          ]
        },
        "customer_id": {
          "type": "string",
          "pattern": "^ctm_[a-z\\d]{26}$",
          "description": "Paddle ID of the customer this usage balance belongs to.",
          "title": "Customer ID",
          "examples": [
            "ctm_01grnn4zta5a1mf02jjze7y2ys"
          ]
        },
        "usage_balance_unit_id": {
          "type": "string",
          "pattern": "^ubu_[a-z\\d]{26}$",
          "description": "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.",
          "title": "Usage Balance Unit ID",
          "examples": [
            "ubu_01kw8ta2j8x5t7q4v9m1kd6phz"
          ]
        },
        "balance": {
          "type": "object",
          "required": [
            "used",
            "remaining",
            "overage"
          ],
          "properties": {
            "used": {
              "properties": {
                "total": {
                  "type": "string",
                  "maxLength": 45,
                  "pattern": "^(0|[1-9][0-9]{0,34})(\\.[0-9]{1,9})?$",
                  "description": "Total across all sources, for example `\"1000\"` or `\"1000.5\"`.",
                  "title": "Usage Amount"
                },
                "subscription": {
                  "type": "string",
                  "maxLength": 45,
                  "pattern": "^(0|[1-9][0-9]{0,34})(\\.[0-9]{1,9})?$",
                  "description": "Amount from allowances on the customer's subscriptions.",
                  "title": "Usage Amount"
                }
              },
              "required": [
                "total",
                "subscription"
              ],
              "type": "object",
              "description": "How much of the allowance the customer has used in the current billing period, broken down by source. Doesn't include overage.",
              "title": "Usage balance amount breakdown"
            },
            "remaining": {
              "properties": {
                "total": {
                  "type": "string",
                  "maxLength": 45,
                  "pattern": "^(0|[1-9][0-9]{0,34})(\\.[0-9]{1,9})?$",
                  "description": "Total across all sources, for example `\"1000\"` or `\"1000.5\"`.",
                  "title": "Usage Amount"
                },
                "subscription": {
                  "type": "string",
                  "maxLength": 45,
                  "pattern": "^(0|[1-9][0-9]{0,34})(\\.[0-9]{1,9})?$",
                  "description": "Amount from allowances on the customer's subscriptions.",
                  "title": "Usage Amount"
                }
              },
              "required": [
                "total",
                "subscription"
              ],
              "type": "object",
              "description": "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\"`.",
              "title": "Usage balance amount breakdown"
            },
            "overage": {
              "properties": {
                "total": {
                  "type": "string",
                  "maxLength": 45,
                  "pattern": "^(0|[1-9][0-9]{0,34})(\\.[0-9]{1,9})?$",
                  "description": "Total overage recorded in the current billing period, for example `\"0\"` or `\"25.5\"`.",
                  "title": "Usage Amount"
                },
                "started_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "When this usage balance first went into overage in the current billing period. Not returned when `total` is `\"0\"`.",
                  "title": "Timestamp",
                  "examples": [
                    "2024-10-12T07:20:50.52Z"
                  ]
                }
              },
              "required": [
                "total"
              ],
              "type": "object",
              "description": "Usage recorded after `remaining` reached `\"0\"` in the current billing period. Paddle doesn't bill for overage, and clears it when the subscription renews.",
              "title": "Usage overage amount"
            }
          },
          "description": "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`.",
          "title": "Usage balance amount"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.",
          "title": "Created at",
          "examples": [
            "2024-10-12T07:20:50.52Z"
          ]
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.",
          "title": "Updated at",
          "examples": [
            "2024-10-13T07:20:50.52Z"
          ]
        }
      },
      "required": [
        "id",
        "customer_id",
        "usage_balance_unit_id",
        "balance",
        "created_at",
        "updated_at"
      ],
      "type": "object",
      "description": "New or changed entity.",
      "title": "Usage balance"
    }
  }
}
```

## Example

```json
{
  "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"
  }
}
```