Create a billable metric

POST

billable_metrics

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",
    "weighted_interval": "seconds",
    "filters": [
      {
        "key": "region",
        "values": ["us-east-1", "us-east-2", "eu-west-1"]
      }
    ]
  }
}'

{
  "billable_metric": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "name": "Storage",
    "code": "storage",
    "description": "GB of storage used in my application",
    "recurring": true,
    "created_at": "2022-09-14T16:35:31Z",
    "field_name": "gb",
    "aggregation_type": "sum_agg",
    "weighted_interval": "seconds",
    "group": {
      "key": "region",
      "values": [
        "us-east-1",
        "us-east-2",
        "eu-west-1"
      ]
    },
    "filters": [
      {
        "key": "region",
        "values": [
          "us-east-1"
        ]
      }
    ],
    "active_subscriptions_count": 4,
    "draft_invoices_count": 10,
    "plans_count": 4
  }
}

Authorizations

Authorization

string

headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

billable_metric

object

required

billable_metric.name

string

required

Name of the billable metric.

billable_metric.code

string

required

Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.

billable_metric.description

string | null

Internal description of the billable metric.

billable_metric.recurring

boolean

Defines if the billable metric is persisted billing period over billing period.

If set to true: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.
If set to false: the accumulated number of units is reset to 0 at the end of the billing period.
If not defined in the request, default value is false.

billable_metric.field_name

string | null

Property of the billable metric used for aggregating usage data. This field is not required for count_agg.

billable_metric.aggregation_type

enum<string>

required

Aggregation method used to compute usage for this billable metric.

Available options:

count_agg,

sum_agg,

max_agg,

unique_count_agg,

weighted_sum_agg,

latest_agg

billable_metric.weighted_interval

enum<string> | null

Parameter exclusively utilized in conjunction with the weighted_sum aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. When this field is not provided, the default time interval is assumed to be in seconds.

Available options:

seconds

billable_metric.group

object

deprecated

Group with one or two dimensions, used to apply differentiated pricing based on additional properties of the billable metric.

billable_metric.filters

object[]

Response

200 - application/json

billable_metric

object

required

billable_metric.lago_id

string

required

Unique identifier of the billable metric created by Lago.

billable_metric.name

string

required

Name of the billable metric.

billable_metric.code

string

required

Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.

billable_metric.description

string | null

Internal description of the billable metric.

billable_metric.recurring

boolean

required

Defines if the billable metric is persisted billing period over billing period.

If set to true: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.
If set to false: the accumulated number of units is reset to 0 at the end of the billing period.
If not defined in the request, default value is false.

billable_metric.created_at

string

required

Creation date of the billable metric.

billable_metric.field_name

string | null

Property of the billable metric used for aggregating usage data. This field is not required for count_agg.

billable_metric.aggregation_type

enum<string>

required

Aggregation method used to compute usage for this billable metric.

Available options:

count_agg,

sum_agg,

max_agg,

unique_count_agg,

weighted_sum_agg,

latest_agg

billable_metric.weighted_interval

enum<string> | null

Available options:

seconds

billable_metric.group

object

deprecated

Group with one or two dimensions, used to apply differentiated pricing based on additional properties of the billable metric.

billable_metric.filters

object[]

billable_metric.active_subscriptions_count

integer

required

Number of active subscriptions using this billable metric.

billable_metric.draft_invoices_count

integer

required

Number of draft invoices for which this billable metric is listed as an invoice item.

billable_metric.plans_count

integer

required

Number of plans using this billable metric.

Was this page helpful?

The billable metric object Update a 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",
    "weighted_interval": "seconds",
    "filters": [
      {
        "key": "region",
        "values": ["us-east-1", "us-east-2", "eu-west-1"]
      }
    ]
  }
}'

{
  "billable_metric": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "name": "Storage",
    "code": "storage",
    "description": "GB of storage used in my application",
    "recurring": true,
    "created_at": "2022-09-14T16:35:31Z",
    "field_name": "gb",
    "aggregation_type": "sum_agg",
    "weighted_interval": "seconds",
    "group": {
      "key": "region",
      "values": [
        "us-east-1",
        "us-east-2",
        "eu-west-1"
      ]
    },
    "filters": [
      {
        "key": "region",
        "values": [
          "us-east-1"
        ]
      }
    ],
    "active_subscriptions_count": 4,
    "draft_invoices_count": 10,
    "plans_count": 4
  }
}

API Reference

Authorizations

Body

Response