Update

PATCH /v0/billableMetrics/{id}

Update

cURL

curl --request PATCH \
  --url https://api.paygentic.io/v0/billableMetrics/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "name": "<string>",
  "unit": "<string>",
  "itemId": "<string>",
  "eventType": "<string>",
  "valueProperty": "<string>",
  "groupBy": {},
  "eventFrom": "2023-11-07T05:31:56Z"
}
'

200

{
  "id": "bm_u3v4w5x6y7z8a9b0",
  "object": "billableMetric",
  "aggregation": "SUM",
  "createdAt": "2024-02-01T14:45:30Z",
  "description": "Language model token consumption",
  "merchantId": "org_c1d2e3f4g5h6i7j8",
  "name": "LLM Tokens",
  "productId": "prod_k9l0m1n2o3p4q5r6",
  "unit": "tokens",
  "updatedAt": "2024-03-15T11:30:00Z"
}

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).

Show child attributes

eventFrom · string<date-time> | null

Only count events after this timestamp.

Response

200

application/json

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

Show child attributes

eventFrom · string<date-time> | null