# Metered features

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


A metered feature object represents two things:

-   the [feature](/docs/api/features) whose entitlement is consumed based on measured usage.
-   the configuration that measures that usage.

## Sample Metered feature

```json
{
  "meter": {
    "id": "API-Calls",
    "name": "API Calls",
    "description": "Number of API calls consumed by the subscription",
    "type": "simple",
    "status": "active",
    "query": "SELECT SUM(request_count) from events",
    "column_definitions": [
      {
        "column_name": "request_count",
        "data_type": "number"
      },
      {..}
    ],
    "features": [
      {
        "id": "API-Calls",
        "name": "API Calls",
        "description": "Number of API calls consumed by the subscription",
        "status": "active",
        "type": "range",
        "unit": "api_call",
        "metered": true,
        "levels": [
          {
            "value": 1,
            "is_unlimited": false
          },
          {..}
        ],
        "resource_version": 1612890000000,
        "updated_at": 1612890000,
        "created_at": 1612890000,
        "object": "feature"
      },
      {..}
    ],
    "object": "meter"
  }
}
```

## Metered features attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique identifier for the metered feature. This is the same as `feature.id`.

- `name` (optional, 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.

- `type` (optional, enumerated string)
  The type of meter. Determines how usage is measured for the metered feature.
  Possible enum values:
    - `simple`
      Usage is computed from a SQL `query` over [`usage_event`](/docs/api/usage_events) properties.
    - `compound`
      Usage is computed from a mathematical formula combining other meters.

- `status` (optional, enumerated string)
  The current status of the metered feature.
  Possible enum values:
    - `active`
      The metered feature is active and **new** [entitlements](/docs/api/entitlements) and [subscription entitlements](/docs/api/subscription_entitlements) can be created for it.
    - `archived`
      No **new** [entitlements](/docs/api/entitlements) and [subscription entitlements](/docs/api/subscription_entitlements) can be created for the metered feature. However, any pre-existing entitlements and subscription entitlements remain effective.
    - `deleted`
      The metered feature has been permanently deleted.

- `query` (optional, string, max chars=500)
  The SQL query used to measure usage from [`usage_event`](/docs/api/usage_events) properties. For example: `SELECT SUM(api_calls) FROM events`.
  
  **Constraint**:
  
  -   The properties referenced in the query are always one of `column_definitions.column_name`.

- `column_definitions` (optional, list of column_definition)
  Definitions of the columns or properties referenced by the metered feature's `query`.

- `features` (optional, list of feature)
  The [feature](/docs/api/features) associated with this metered feature. This array has only one element since any given metered feature is associated with only one feature.

## Column definition attributes

## Input Parameters

- `column_name` (required, string, max chars=100)
  Name of the column or property used in the `query`. For example, `request_count` or `input_tokens`.

- `data_type` (required, enumerated string)
  Data type of the column or property.
  Possible enum values:
    - `number`
      The column or property holds a numeric value.
    - `string`
      The column or property holds a string value.

## Feature attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique and immutable identifier for the feature. This is the same as `id`.

- `name` (required, string, max chars=50)
  A case-sensitive unique name for the feature.

- `description` (optional, string, max chars=500)
  A brief description of the feature.

- `status` (optional, enumerated string)
  The current status of the feature.
  Possible enum values:
    - `active`
      The feature is active. Any [entitlements](/docs/api/entitlements) or [subscription entitlements](/docs/api/subscription_entitlements) defined for the feature take effect immediately.
    - `archived`
      No **new** [entitlements](/docs/api/entitlements) or [subscription entitlements](/docs/api/subscription_entitlements) can be created for the feature. However, any pre-existing entitlements and subscription entitlements remain effective.
    - `draft`
      This value is not applicable for metered features.

- `type` (optional, enumerated string)
  The type of feature. The value is always `range`.
  Possible enum values:
    - `switch`
      This value is not applicable for metered features.
    - `custom`
      This value is not applicable for metered features.
    - `quantity`
      This value is not applicable for metered features.
    - `range`
      The feature is quantity based, with entitlement levels between `1` and `unlimited`.

- `unit` (optional, string, max chars=50)
  Specifies the unit of measure. The value is expected in the singular form. It is pluralized automatically as needed. For example, for a feature such as `API Calls`, the `unit` can be `request`.

- `resource_version` (optional, long)
  The version number of this resource. For every change made to the resource, `resource_version` is updated with a new timestamp in milliseconds.

- `updated_at` (optional, timestamp(UTC) in seconds)
  When the feature was last updated.

- `created_at` (required, timestamp(UTC) in seconds)
  When the feature was created.

- `metered` (required, boolean)
  Indicates whether the feature is metered. The value is always `true`.

- `levels` (optional, list of level)
  An ordered list of entitlement levels available for the feature.
  - `name` (optional, string, max chars=50)
    A case-sensitive display name for the entitlement level.
  - `value` (required, string, max chars=50)
    Always `1` for `levels[0]` and `unlimited` for `levels[1]`.
  - `level` (required, integer)
    This attribute represents the order of the entitlement levels from lowest to highest.
  - `is_unlimited` (required, boolean)
    Always `true` for `levels[1]` and `false` for `levels[0]`.