---
title: "Create a billable metric"
method: POST
path: "/api/billable-metrics"
tags: ["Billable Metrics"]
---

# Create a billable metric

`POST /api/billable-metrics`

Create a new billable metric for usage-based billing. Supported aggregation types: COUNT, SUM, MAX, UNIQUE_COUNT, LATEST, WEIGHTED_SUM.

## Request body

- CreateBillableMetricDto
  - `name` string, required
  - `code` string, required — Unique metric code
  - `description` string
  - `aggregationType` 'COUNT' | 'SUM' | 'MAX' | 'UNIQUE_COUNT' | 'LATEST' | 'WEIGHTED_SUM', required
  - `fieldName` string — Property key to aggregate (required for SUM, MAX, LATEST, WEIGHTED_SUM)
  - `recurring` boolean — If true, value carries forward across billing periods
  - `filters` CreateBillableMetricFilterDto[]
    - `key` string, required — Property key to filter on
    - `values` string[], required — Allowed values

## Response `201`

Billable metric created

- BillableMetricResponse
  - `id` string, required
  - `name` string, required
  - `code` string, required
  - `description` string
  - `aggregationType` 'COUNT' | 'SUM' | 'MAX' | 'UNIQUE_COUNT' | 'LATEST' | 'WEIGHTED_SUM', required
  - `fieldName` string
  - `recurring` boolean, required
  - `filters` BillableMetricFilterResponse[], required
    - `id` string, required
    - `billableMetricId` string, required
    - `key` string, required
    - `values` string[], required
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `409` — Metric with this code already exists

---

[API](https://skmtc.net/novabilling/apis/novabilling-api.md) · [All operations](https://skmtc.net/novabilling/apis/novabilling-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novabilling/novabilling-api/versions/0e449a4e0dc8/schema)