Meters

Meter and usage reporting endpoints

List meter subscriptions by ID

GET

https://api.ledgerbee.com/api

/v1/meters/{meterId}/subscriptions

x-api-key (header)

OAuth 2.0

Looks up a meter by its UUID and returns the subscriptions (with their products) that can report usage to it — i.e. subscriptions holding a product whose price is linked to this meter. Paused subscriptions are excluded.

Returns an empty subscriptions array when no product price uses the meter. Responds 404 with code METER_NOT_FOUND if the meter does not exist in your company.

Required Scope

meter-report

Required License

Subscription — the tenant must hold this module license, or the request returns 403 LICENSE.REQUIRED.

List meter subscriptions by ID › path Parameters

meterId

string · required

The unique identifier of the meter

Example: 550e8400-e29b-41d4-a716-446655440000

List meter subscriptions by ID › Responses

Subscriptions and products that can report usage to this meter

MeterSubscriptionsResponseDTO

meterId

string · required

Meter ID

Example: 550e8400-e29b-41d4-a716-446655440000

meterName

string · required

Meter name

Example: api_calls

MeterSubscriptionDTO[] · required

Subscriptions with products using this meter

Report usage

POST

https://api.ledgerbee.com/api

/v1/meters/report

x-api-key (header)

Reports a usage event to a meter for metered subscription billing. Ingestion is asynchronous: a successful report returns 202 with status: queued and a requestId — the event is not yet visible the moment the call returns.

The Idempotency-Key header is required (400 when missing). Replaying a request with the same key returns 200 with status: duplicate and the event is not ingested twice, so retries are always safe.

Use the meter-subscriptions endpoints to discover which subscriptions and products can report usage to a given meter.

How usage is aggregated

Each meter has an aggregation method, fixed when the meter is created, that determines how the events you report become the single quantity billed for the period:

sum — adds every reported value together (e.g. tokens used, GB transferred).
count — counts how many events you report; the value you send is ignored.
last — uses the value of the most recent event in the period, by event timestamp (e.g. a current seat count).

value is always required by this endpoint, but for a count meter it is not used in the calculation — send any non-negative number.

The aggregation method can't be changed once usage has been reported to a meter; create a new meter to bill the same events a different way.

Required Scope

meter-report

Required License

Metered Products — the tenant must also hold this module license, or the request returns 403 LICENSE.REQUIRED.

Report usage › Headers

x-api-idempotency-key

string · maxLength: 255 · required

Idempotency key to deduplicate submissions

Report usage › Request Body

UsageReportRequestDto

value

number · required

The numeric value of this usage event. How it is used depends on the meter's aggregation method: summed (sum) or taken as the latest value (last). For count meters the value is ignored, but a non-negative number is still required.

Example: 100

customerId

string · required

Customer ID this usage is associated with.

Example: 550e8400-e29b-41d4-a716-446655440000

meterId

string

Meter identifier. Provide meterId or meterName. Meter must be ACTIVE; usage will be rejected for archived meters.

Example: 550e8400-e29b-41d4-a716-446655440000

meterName

string

Meter name. Provide meterId or meterName. Meter must be ACTIVE; usage will be rejected for archived meters.

Example: api_calls

timestamp

string

ISO-8601 timestamp. Defaults to now.

Example: 2024-01-15T10:30:00Z

dimension

string · maxLength: 100

What the quantity is measured PER — a seat, a device, a user. Only a meter using the max_per_dimension aggregation reads it; every other aggregation ignores it.

This is a GROUPING key, not a label: the meter bills the peak each dimension reached, added together, so the value must identify a thing that persists across reports. Put descriptive detail in metadata instead, which is never aggregated on.

A value that is unique per report defeats the aggregation, and a meter is refused new dimensions once it carries too many distinct values.

Example: seat-4f21

metadata

object

Additional metadata for the usage event (values must be string, number, or boolean)

Example: {"region":"us-east-1","feature":"api-calls"}

Report usage › Responses

Duplicate request detected

status

string

idempotencyKey

string

POST/v1/meters/report

curl https://api.ledgerbee.com/api/v1/meters/report \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-idempotency-key: <string>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "meterId": "550e8400-e29b-41d4-a716-446655440000",
  "meterName": "api_calls",
  "value": 100,
  "timestamp": "2024-01-15T10:30:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "dimension": "seat-4f21",
  "metadata": {
    "region": "us-east-1",
    "feature": "api-calls"
  }
}'

Example Request Body

{
  "meterId": "550e8400-e29b-41d4-a716-446655440000",
  "meterName": "api_calls",
  "value": 100,
  "timestamp": "2024-01-15T10:30:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "dimension": "seat-4f21",
  "metadata": {
    "region": "us-east-1",
    "feature": "api-calls"
  }
}

json

application/json

Example Responses

{
  "status": "duplicate",
  "idempotencyKey": "idempotencyKey"
}

json

application/json

List meter subscriptions by name

GET

https://api.ledgerbee.com/api

/v1/meters/subscriptions

x-api-key (header)

OAuth 2.0

Looks up a meter by its name (?meterName=) and returns the subscriptions (with their products) that can report usage to it — useful when your integration knows the meter's name (e.g. api_calls) but not its UUID. Paused subscriptions are excluded.

Returns an empty subscriptions array when no product price uses the meter. Responds 400 with code METER_IDENTIFIER_REQUIRED when meterName is missing, and 404 with code METER_NOT_FOUND if no meter has that name in your company.

Required Scope

meter-report

Required License

Subscription — the tenant must hold this module license, or the request returns 403 LICENSE.REQUIRED.

List meter subscriptions by name › query Parameters

meterName

string · required

The name of the meter to look up

List meter subscriptions by name › Responses

Subscriptions and products that can report usage to this meter (lookup by name)

MeterSubscriptionsResponseDTO

meterId

string · required

Meter ID

Example: 550e8400-e29b-41d4-a716-446655440000

meterName

string · required

Meter name

Example: api_calls

MeterSubscriptionDTO[] · required

Subscriptions with products using this meter

MCP Open Entries

LedgerBee Public API

Meters

Download schema

Meter and usage reporting endpoints

List meter subscriptions by ID

GET

https://api.ledgerbee.com/api

/v1/meters/{meterId}/subscriptions

x-api-key (header)

OAuth 2.0

Returns an empty subscriptions array when no product price uses the meter. Responds 404 with code METER_NOT_FOUND if the meter does not exist in your company.

Required Scope

meter-report

Required License

Subscription — the tenant must hold this module license, or the request returns 403 LICENSE.REQUIRED.

List meter subscriptions by ID › path Parameters

meterId

string · required

The unique identifier of the meter

Example: 550e8400-e29b-41d4-a716-446655440000

List meter subscriptions by ID › Responses

Subscriptions and products that can report usage to this meter

MeterSubscriptionsResponseDTO

meterId

string · required

Meter ID

Example: 550e8400-e29b-41d4-a716-446655440000

meterName

string · required

Meter name

Example: api_calls

MeterSubscriptionDTO[] · required

Subscriptions with products using this meter

Report usage

POST

https://api.ledgerbee.com/api

/v1/meters/report

x-api-key (header)

Use the meter-subscriptions endpoints to discover which subscriptions and products can report usage to a given meter.

How usage is aggregated

Each meter has an aggregation method, fixed when the meter is created, that determines how the events you report become the single quantity billed for the period:

sum — adds every reported value together (e.g. tokens used, GB transferred).
count — counts how many events you report; the value you send is ignored.
last — uses the value of the most recent event in the period, by event timestamp (e.g. a current seat count).

value is always required by this endpoint, but for a count meter it is not used in the calculation — send any non-negative number.

The aggregation method can't be changed once usage has been reported to a meter; create a new meter to bill the same events a different way.

Required Scope

meter-report

Required License

Metered Products — the tenant must also hold this module license, or the request returns 403 LICENSE.REQUIRED.

Report usage › Headers

x-api-idempotency-key

string · maxLength: 255 · required

Idempotency key to deduplicate submissions

Report usage › Request Body

UsageReportRequestDto

value

number · required

Example: 100

customerId

string · required

Customer ID this usage is associated with.

Example: 550e8400-e29b-41d4-a716-446655440000

meterId

string

Meter identifier. Provide meterId or meterName. Meter must be ACTIVE; usage will be rejected for archived meters.

Example: 550e8400-e29b-41d4-a716-446655440000

meterName

string

Meter name. Provide meterId or meterName. Meter must be ACTIVE; usage will be rejected for archived meters.

Example: api_calls

timestamp

string

ISO-8601 timestamp. Defaults to now.

Example: 2024-01-15T10:30:00Z

dimension

string · maxLength: 100

What the quantity is measured PER — a seat, a device, a user. Only a meter using the max_per_dimension aggregation reads it; every other aggregation ignores it.

A value that is unique per report defeats the aggregation, and a meter is refused new dimensions once it carries too many distinct values.

Example: seat-4f21

metadata

object

Additional metadata for the usage event (values must be string, number, or boolean)

Example: {"region":"us-east-1","feature":"api-calls"}

Report usage › Responses

Duplicate request detected

status

string

idempotencyKey

string

POST/v1/meters/report

curl https://api.ledgerbee.com/api/v1/meters/report \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-idempotency-key: <string>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "meterId": "550e8400-e29b-41d4-a716-446655440000",
  "meterName": "api_calls",
  "value": 100,
  "timestamp": "2024-01-15T10:30:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "dimension": "seat-4f21",
  "metadata": {
    "region": "us-east-1",
    "feature": "api-calls"
  }
}'

Example Request Body

{
  "meterId": "550e8400-e29b-41d4-a716-446655440000",
  "meterName": "api_calls",
  "value": 100,
  "timestamp": "2024-01-15T10:30:00Z",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "dimension": "seat-4f21",
  "metadata": {
    "region": "us-east-1",
    "feature": "api-calls"
  }
}

json

application/json

Example Responses

{
  "status": "duplicate",
  "idempotencyKey": "idempotencyKey"
}

json

application/json

List meter subscriptions by name

GET

https://api.ledgerbee.com/api

/v1/meters/subscriptions

x-api-key (header)

OAuth 2.0

Required Scope

meter-report

Required License

Subscription — the tenant must hold this module license, or the request returns 403 LICENSE.REQUIRED.

List meter subscriptions by name › query Parameters

meterName

string · required

The name of the meter to look up

List meter subscriptions by name › Responses

Subscriptions and products that can report usage to this meter (lookup by name)

MeterSubscriptionsResponseDTO

meterId

string · required

Meter ID

Example: 550e8400-e29b-41d4-a716-446655440000

meterName

string · required

Meter name

Example: api_calls

MeterSubscriptionDTO[] · required

Subscriptions with products using this meter

MCP Open Entries