Create billable metric

Route

POST

/api/v1/billable_metrics

Usage

Curl

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": "bm_name",
      "code": "bm_code",
      "description": "description",
      "aggregation_type": "sum_agg",
      "field_name": "amount_sum",
      "group": {
        "key": "region",
        "value": ["USA", "EUROPE"]
      }
    }
  }'

Python

from lago_python_client import Client
from lago_python_client.models import BillableMetricGroup, BillableMetric

client = Client(api_key='__YOUR_API_KEY__')

group = BillableMetricGroup(
  key='country',
  values=['france', 'italy', 'spain']
)

billable_metric = BillableMetric(
  name='name',
  code='code_first',
  description='desc',
  aggregation_type='sum_agg',
  field_name='amount_sum',
  group=group
)
client.billable_metrics().create(billable_metric)

Ruby

require 'lago-ruby-client'

client = Lago::Api::Client.new({api_key: '__YOUR_API_KEY__'})

client.billable_metrics.create({
  name: 'BM1',
  code: 'code_bm',
  description: 'description',
  aggregation_type: 'sum_agg',
  field_name: 'amount_sum',
  group: {
    key: 'country',
    values: %w[france italy spain]
  }
})

Node.js

import BillableMetric from 'lago-nodejs-client/billable_metric'

let client = new Client('__API_KEY__')

let billableMetric = new BillableMetric({
    name: 'name1',
    code: 'code1',
    aggregationType: 'sum_agg',
    fieldName: 'field_name',
    group: {
      key: 'country',
      values: ["france", "italy", "spain"]
    }
})
await client.createBillableMetric(billableMetric);

Go

  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    bmInput := &lago.BillableMetricInput{
      Name:            "First Billable Metric",
      Code:            "first_bm",
      Description:     "My First Billable Metric"
      AggregationType: lago.CountAggregation,
      FieldName:       "sum",
      Group: map[string]interface{}{
          "key": "country",
          "values": [3]string{"france", "italy", "spain"},
      },
    }

    billableMetric, err := lagoClient.BillableMetric().Create(bmInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // billableMetric is *lago.BillableMetric
    fmt.Println(billableMetric)
  }

Arguments

{
  "billable_metric": {
    "name": "bm_name",
    "code": "bm_code",
    "description": "description",
    "aggregation_type": "sum_agg",
    "field_name": "amount_sum",
    "group": {
      "key": "country",
      "values": ["france", "italy", "spain"]
    }
  }
}

Attributes	Type	Description
name	String      Required	Billable metric name
code	String      Required	Code identifying the billable metric
description	String      Optional	Description of the billable metric
aggregation_type	String      Required	Aggregation type that is used in event calculations. It can be count_agg (metered), sum_agg (metered), max_agg (metered), unique_count_agg (metered) or recurring_count_agg (persistent)
field_name	String      Required (optional only for count_agg aggregation type)	Field name used in events.
group	Object      Optional	Group (one or two dimensions) for pricing differently the billable metric

Group - One dimension

Attributes	Type	Description
key	String      Required	Name of the event's field used for grouping
values	Array      Required	Array of string representing all possible values

Example:

{
  "group": {
    "key": "country",
    "values": ["france", "italy", "spain"]
  }
}

Group - Two dimensions

Attributes	Type	Description
key	String      Required	Name of the first event's field used for grouping
values	Array      Required	Array of objects representing all possible values

Values:

Attributes	Type	Description
name	String      Required	Value for the first dimension of the group
key	Array      Required	Name of the second event's field used for grouping
values	Array      Required	Array of string representing all possible values of the second dimension

Example:

{
  "group": {
    "key": "cloud",
    "values": [
      {
        "name": "AWS",
        "key": "region",
        "values": ["USA", "EUROPE"]
      }, {
        "name": "Google",
        "key": "region",
        "values": ["USA"]
      }
    ]
  }
}

Responses

HTTP 200

The billable metric was created

Returns a billable metric object.

HTTP 400

{
  "status": 400,
  "error": "Bad Request"
}

The billable_metric json root is not present in the request body.

HTTP 401

{
  "status": 401,
  "error": "Unauthorized"
}

Access to the API endpoint is unhautorized.

Possible reasons are:

• The Authorization header is missing
• The Authorization header does not contain the API key
• The Api key is invalid or expired

HTTP 422

{
  "status": 422,
  "error": "Unprocessable entity",
  "code": "validation_errors",
  "error_details": {
    "field": ["error"]
  }
}

Possible errors:

Field	Code	Description
name	value_is_mandatory	name value is missing
code	value_is_mandatory	code value is missing
code	value_already_exists	code value is already used for another billable metric
field_name	value_is_mandatory	field_name value is missing
aggregation_type	value_is_invalid	Provided aggregation_type value is invalid
group	value_is_invalid	Format of provided JSON for group is invalid