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

meter.created

Occurs when a meter is created.

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 a meter is created. A meter maps an action that you report usage for to the usage balance unit that it draws down.

meter.updated occurs when a meter changes, including when it's archived.

Payload includes the complete meter entity.

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: mtr_01kvqjfc6eb9kzk7s2wvz2aamq
Unique Paddle ID for this meter entity, prefixed with mtr_.
Pattern: ^mtr_[a-z\d]{26}$
revision_idstringrequired
Example: mtrrev_01kw8tb5n2y6c3r8w4p2ke7qja
Unique Paddle ID for this meter entity revision, prefixed with mtrrev_. Changes each time the meter is updated, so you can tell which version of a meter a webhook event refers to.
Pattern: ^mtrrev_[a-z\d]{26}$
usage_balance_unit_idstringrequired
Example: ubu_01kw8ta2j8x5t7q4v9m1kd6phz
Paddle ID of the usage balance unit that this meter draws down, prefixed with ubu_. Can't be changed after you create the meter.
Pattern: ^ubu_[a-z\d]{26}$
namestringrequired
Name of this meter, shown in the Paddle dashboard.
Length: 1–255
Pattern: .*\S.*
actionstringrequired
Action that you record usage events for, like api_call. Paddle matches usage events to this meter using their action. More than one meter can have the same action, as long as each draws down a different usage balance unit. A usage event then draws down the customer's usage balance for each of them.
Length: 2–64
Pattern: ^[a-z][a-z0-9_]*$
descriptionstring | nullrequired
Short description for this meter.
Max length: 2048
aggregationstringrequired
How this meter aggregates usage events into a usage total.
Values
  • sum
    Adds up the quantity of each usage event.
unit_namestringrequired
Singular name of what this meter measures, like call or token. Shown alongside usage totals. Different from the usage balance unit's unit_name, which is the plural name of what customers hold a balance of.
Length: 1–64
ratestringrequired
How much of the usage balance unit that one unit of usage draws down. For example, "1" draws down one unit of the balance for each unit of usage, and "0.001" draws down one unit of the balance for every 1,000 units of usage. A decimal string greater than zero, with up to 9 decimal places.
Max length: 45
Pattern: ^([1-9][0-9]{0,34}(\.[0-9]{1,9})?|0\.(?:[1-9][0-9]{0,8}|0[1-9][0-9]{0,7}|00[1-9][0-9]{0,6}|000[1-9][0-9]{0,5}|0000[1-9][0-9]{0,4}|00000[1-9][0-9]{0,3}|000000[1-9][0-9]{0,2}|0000000[1-9][0-9]?|00000000[1-9]))$
statusstringrequired
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
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.
meter.created
{
  "event_id": "evt_01kw8tj8fq5rp3n7m0h9d4vsb2",
  "event_type": "meter.created",
  "occurred_at": "2026-09-01T09:10:00.283806Z",
  "notification_id": "ntf_01kw8tj9k7v2ah6y8pxr3q1nfe",
  "data": {
    "id": "mtr_01kvqjfc6eb9kzk7s2wvz2aamq",
    "revision_id": "mtrrev_01kvqjfc6eb9kzk7s2wvz2aamq",
    "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
    "name": "API calls",
    "action": "api_call",
    "description": "Calls to the public API",
    "aggregation": "sum",
    "unit_name": "call",
    "rate": "1",
    "status": "active",
    "custom_data": null,
    "created_at": "2026-09-01T09:10:00Z",
    "updated_at": "2026-09-01T09:10:00Z"
  }
}

Was this page helpful?