Skip to main content
POST
/
v0
/
billableMetrics
Create
curl --request POST \
  --url https://api.paygentic.io/v0/billableMetrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "aggregation": "SUM",
  "description": "<string>",
  "merchantId": "<string>",
  "name": "<string>",
  "productId": "<string>",
  "unit": "<string>",
  "eventType": "<string>",
  "valueProperty": "<string>",
  "groupBy": {},
  "eventFrom": "2023-11-07T05:31:56Z"
}
'
{
  "id": "bm_w9x0y1z2a3b4c5d6",
  "object": "billableMetric",
  "aggregation": "SUM",
  "createdAt": "2024-01-15T10:30:00Z",
  "description": "Total tokens consumed by Claude language model interactions",
  "merchantId": "org_e7f8g9h0i1j2k3l4",
  "name": "Claude Tokens",
  "productId": "prod_m5n6o7p8q9r0s1t2",
  "taxRate": 8.5,
  "unit": "tokens",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication

Body

application/json
​
aggregation
enum<string>
required

Aggregation calculation method for metric values.

Available options:
SUM,
COUNT,
AVG,
MIN,
MAX,
UNIQUE_COUNT,
LATEST
​
description
string
required

Explanatory text describing what the metric tracks and how it's used for billing. Sample values: 'Total tokens consumed by Claude language model interactions', 'Gigabytes of cloud storage utilized', 'Count of machine learning inference requests processed', 'Quantity of AI-generated images created', 'Compute hours spent training neural networks', 'Terabytes of data transferred'

​
merchantId
string
required

The unique identifier of the merchant organization associated with the billable metric.

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

Human-readable label identifying what this metric measures. Sample values: 'Claude Tokens', 'Storage Capacity', 'Model Inference Calls', 'Generated Images', 'Training Compute Hours', 'Data Transfer Volume'

​
productId
string
required

The unique identifier of the product associated with the billable metric.

Pattern: ^prod_[a-zA-Z0-9]+$
​
unit
string
required

Measurement unit used when aggregating this metric's values. Common examples: 'tokens', 'GB', 'calls', 'images', 'hours', 'TB', 'queries', 'requests'

​
eventType
string

CloudEvents type for meter routing. Links this billable metric to the metering service.

​
valueProperty
string

JSONPath to extract numeric value from event data. Required for SUM/AVG/MIN/MAX/LATEST aggregations.

​
groupBy
object

Map of dimension name to JSONPath for group-by queries.

​
eventFrom
string<date-time>

Only count events after this timestamp. Used for meter versioning.

Response

Billable metric created 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

Unique identifier for a product

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