Skip to main content
PATCH
Update

Authorizations

Authorization
string
header
required

API key authentication

Path Parameters

id
string
required

Unique identifier for a billable metric

Pattern: ^bm_[a-zA-Z0-9]+$

Body

application/json
description
string

Revised explanation of what the metric represents. Sample values: 'Language model token consumption', 'Database storage capacity used', 'Machine learning prediction API calls', 'AI-generated content items'

name
string

Updated label for the metric. Sample values: 'LLM Tokens', 'Database Storage', 'Prediction Requests', 'Content Generations'

unit
string

Updated measurement unit. Common examples: 'tokens', 'GB', 'requests', 'items', 'hours'

itemId
string | null

Optional item tag, used to map this metric's invoice lines to an external accounting/tax identity. Send a new id to re-tag — the item must be filed under this charge's own product, and an archived item is rejected. An item from another product is refused with ITEM_PRODUCT_MISMATCH: a tag is an accounting grouping and does not move the charge between products, and no field here could move it back. Re-file the item to move every charge anchored to it together. Send null to untag. Every line item whose invoice has not closed reports this charge's current tag, so a re-tag takes effect on the bill in progress and on any generated ahead of it — no further action, and no window to wait for. Lines on a closed invoice keep the item recorded at close and never move. Un-tagging works the same way: those lines report no item.

Pattern: ^itm_[a-zA-Z0-9]+$
eventType
string | null

CloudEvents type for meter routing.

valueProperty
string | null

JSONPath to extract a numeric value from event data. Must start with $. (example: $.amount or $.payload.bytes).

Pattern: ^\$\.[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*$
groupBy
object | null

Map of dimension name to JSONPath for group-by queries. Each value must start with $. (example: $.region).

eventFrom
string<date-time> | null

Only count events after this timestamp.

Response

Billable metric updated successfully

id
string
required

Unique identifier for a billable metric

Pattern: ^bm_[a-zA-Z0-9]+$
object
enum<string>
default:billableMetric
required
Available options:
billableMetric
aggregation
enum<string>
required
Available options:
SUM,
COUNT,
AVG,
MIN,
MAX,
UNIQUE_COUNT,
LATEST
createdAt
string<date-time>
required
description
string
required
merchantId
string
required

Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
name
string
required
productId
string
required

The product this metric belongs to. Always populated; derived from the item's catalog when the metric is tagged with an item.

Pattern: ^prod_[a-zA-Z0-9]+$
itemId
string | null
required

The item this metric is tagged with, or null when untagged. Used to map this metric's invoice lines to an external accounting/tax identity.

Pattern: ^itm_[a-zA-Z0-9]+$
unit
string
required
updatedAt
string<date-time>
required
eventType
string | null
valueProperty
string | null
groupBy
object | null
eventFrom
string<date-time> | null