v2

latestOpenAPI 3.0.0raw.githubusercontent.com2026-02-16143114179.4 KB

Charges

Create a charge

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

post/api/charges

Request body

planIdstring required

Plan ID to attach this charge to

billableMetricIdstring required

Billable metric ID

chargeModel'STANDARD' | 'GRADUATED' | 'VOLUME' | 'PACKAGE' | 'PERCENTAGE' required

billingTiming'IN_ADVANCE' | 'IN_ARREARS'

invoiceDisplayNamestring

Display name on invoices

minAmountCentsnumber

Minimum charge in cents

proratedboolean

propertiesobject

Model-specific config. Standard: { amount, currency }. Package: { amount, packageSize, currency }. Percentage: { rate, fixedAmount, freeUnitsPerEvent, freeUnitsPerTotalAggregation }

Example request

{
  "chargeModel": "STANDARD",
  "invoiceDisplayName": "API Calls",
  "minAmountCents": 100,
  "properties": {
    "amount": "0.10",
    "currency": "USD"
  },
  "graduatedRanges": [
    {
      "toValue": 100,
      "perUnitAmount": 0.1
    }
  ],
  "filters": [
    {
      "key": "region",
      "values": [
        "us-east"
      ]
    }
  ]
}

Response

Charge created

idstring required

planIdstring required

billableMetricIdstring required

chargeModel'STANDARD' | 'GRADUATED' | 'VOLUME' | 'PACKAGE' | 'PERCENTAGE' required

billingTiming'IN_ADVANCE' | 'IN_ARREARS' required

invoiceDisplayNamestring

minAmountCentsnumber

proratedboolean required

propertiesobject

Model-specific config

createdAtstring required

updatedAtstring required

Example response

{
  "id": "clx1234567890",
  "planId": "clxplan123",
  "billableMetricId": "clxbm123",
  "chargeModel": "GRADUATED",
  "billingTiming": "IN_ARREARS",
  "invoiceDisplayName": "API Usage",
  "minAmountCents": 100,
  "graduatedRanges": [
    {
      "id": "clx1234567890",
      "toValue": 1000,
      "perUnitAmount": "0.0100",
      "flatAmount": "0.0000"
    }
  ],
  "filters": [
    {
      "id": "clx1234567890",
      "key": "region",
      "values": [
        "us-east"
      ]
    }
  ]
}