Metered vs Recurring

Usage-based charges can be either metered or recurring

A usage-based charge is either metered or recurring. The difference is what happens to the units it counts at the end of a billing period: metered charges reset, recurring charges carry forward.

Metered charges

Dashboard

Set recurring to false on the billable metric to make a charge metered. At the end of each billing period, the units accumulated for the metric reset to 0, so counting starts fresh with each new cycle. Use this for usage that does not persist across periods.

The API tab shows a Storage metric as an example. To track the gigabytes stored during a month, the value resets to 0 at the start of each month.

API

Create a billable metric with recurring set to false.

Metered billable metric

  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "billable_metric": {
      "name": "Storage",
      "code": "storage",
      "description": "GB of storage used in my application",
      "aggregation_type": "sum_agg",
      "recurring": false,
      "field_name": "gb",
      "filters": [
          {
              "key": "region",
              "values": ["us-east-1", "us-east-2", "eu-west-1"]
          }
      ]
    }
  }'

Recurring charges

Dashboard

Set recurring to true on the billable metric to carry units forward. At the end of each billing period, the units accumulated in that period carry over to the next one, so counting continues from the last recorded value. Use this for usage that persists from one period to the next.

The API tab shows a Seats metric as an example. The number of active seats persists month over month, so Lago maintains the count across periods instead of resetting it.

API

Create a billable metric with recurring set to true.

Recurring billable metric

  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "billable_metric": {
      "name": "Seats",
      "code": "seats",
      "description": "Active seats.",
      "aggregation_type": "unique_count_agg",
      "recurring": true,
      "field_name": "seat_id",
      "filters": [
          {
              "key": "type",
              "values": ["admin", "viewer", "editor"]
          }
      ]
    }
  }'