Introducing Chargebee CLI — query billing data, test webhooks, and generate code samples from your terminal.
chargebee api

Create a metered feature

Idempotency Supported

Creates a metered feature.

Use query to define how Chargebee measures usage for the metered feature. The result is a single aggregate across all matching usage events. To report grouped usage, include attributes in a GROUP BY clause. Each distinct set of values forms one usage group. These attributes are the metered feature's group-by attributes.

Availability

Support for adding GROUP BY to metered features and retrieving usage grouped by attributes is an upcoming capability and is not generally available yet. It will be made available in the coming weeks.

Use Cases

Sample Request

Create a metered feature with group-by attributes
Create a metered feature without group-by attributes

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/metered_features

Input Parameters

name
required, string, max chars=50

A case-sensitive name for the metered feature. For example: API Calls, Input Tokens.

description
optional, string, max chars=250

A brief description of the metered feature.

feature_unit
required, string, max chars=50

Unit of measure for the metered feature, in singular form. It is pluralized automatically as needed. For example, request or token.

query
required, string, max chars=1000

The SQL query used to calculate usage from usage_event properties. For example: SELECT SUM(api_calls) FROM events WHERE status = 'completed'.

To group usage by attribute values, include a GROUP BY clause. Each distinct set of group-by attribute values forms a separate usage group. For example: SELECT SUM(hours) FROM events WHERE status = 'completed' GROUP BY gpu_type, region. The response returns the group-by attribute names in group_by, in the same order.

Availability

Support for adding GROUP BY to metered features and retrieving usage grouped by attributes is an upcoming capability and is not generally available yet. It will be made available in the coming weeks.

Constraints

  • Properties used in the aggregate expression or WHERE clause must be listed in column_definitions.column_name.
  • A group-by attribute used only in the GROUP BY clause does not require a column_definitions entry. Its value is treated as a string.
  • The GROUP BY clause can contain up to 5 group-by attributes.
  • Exact duplicate group-by attribute names are not allowed. Names are case-sensitive, so region, region is invalid, while region, Region identifies two different attributes.

Usage reporting and subscription billing

For a metered feature whose query includes a GROUP BY clause, grouped usage is available in Retrieve usage summary for a subscription and Retrieve usages for an invoice as PDF. These groups are for reporting only. Subscription billing uses the overall aggregate for the metered feature and does not bill each group separately.

For example, a SUM query can return 60 hours for region=us-east and 40 hours for region=eu-west. The reporting operations can display both groups. Subscription billing uses the overall aggregate of 100 hours.

column_definitions[0..n]
Parameters for column_definitions. Multiple column_definitions can be passed by specifying unique indices.
pass parameters as column_definitions[<param name>][<idx:0..n>]

Returns

meter
Meter object

Resource object representing the meter for the metered feature.