---
title: "Create a charge"
method: POST
path: "/api/charges"
tags: ["Charges"]
---

# Create a charge

`POST /api/charges`

Create a usage-based charge linking a plan to a billable metric. Supported models: STANDARD, GRADUATED, VOLUME, PACKAGE, PERCENTAGE.

## Request body

- CreateChargeDto
  - `planId` string, required — Plan ID to attach this charge to
  - `billableMetricId` string, required — Billable metric ID
  - `chargeModel` 'STANDARD' | 'GRADUATED' | 'VOLUME' | 'PACKAGE' | 'PERCENTAGE', required
  - `billingTiming` 'IN_ADVANCE' | 'IN_ARREARS'
  - `invoiceDisplayName` string — Display name on invoices
  - `minAmountCents` number — Minimum charge in cents
  - `prorated` boolean
  - `properties` object — Model-specific config. Standard: { amount, currency }. Package: { amount, packageSize, currency }. Percentage: { rate, fixedAmount, freeUnitsPerEvent, freeUnitsPerTotalAggregation }
  - `graduatedRanges` GraduatedRangeDto[] — Required for GRADUATED and VOLUME charge models
    - `fromValue` number, required — Start of range (inclusive)
    - `toValue` number — End of range (inclusive), null = infinity
    - `perUnitAmount` number, required — Price per unit in this range
    - `flatAmount` number — Flat fee for entering this range
  - `filters` ChargeFilterDto[]
    - `key` string, required — Filter key (must match metric filter)
    - `values` string[], required — Subset of allowed values
    - `properties` object — Override properties for this filter

## Response `201`

Charge created

- ChargeResponse
  - `id` string, required
  - `planId` string, required
  - `billableMetricId` string, required
  - `chargeModel` 'STANDARD' | 'GRADUATED' | 'VOLUME' | 'PACKAGE' | 'PERCENTAGE', required
  - `billingTiming` 'IN_ADVANCE' | 'IN_ARREARS', required
  - `invoiceDisplayName` string
  - `minAmountCents` number
  - `prorated` boolean, required
  - `properties` object — Model-specific config
  - `graduatedRanges` ChargeGraduatedRangeResponse[], required
    - `id` string, required
    - `chargeId` string, required
    - `fromValue` number, required
    - `toValue` number
    - `perUnitAmount` string, required — Per-unit amount as decimal string
    - `flatAmount` string, required — Flat fee for this range
    - `order` number, required
  - `filters` ChargeFilterResponse[], required
    - `id` string, required
    - `chargeId` string, required
    - `key` string, required
    - `values` string[], required
    - `properties` object
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `404` — Plan or metric not found
- `409` — Charge for this metric already exists on plan

---

[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/revisions/0e449a4e0dc8/schema)