​
Grouping with a single key

Consider the following example:

Your company provides DevOps services and you want to charge your customers for compute capacity by the hour.

In your Lago account, you create a compute billable metric that calculates the total number of hours (i.e. SUM(properties.hours)).

As your customers can choose from different cloud providers, you need to group usage records (i.e. events) according to the provider.

On the configuration page of your billable metric, you can define "key": "provider" and "values": ["AWS","Google","Azure"] to create the corresponding dimension (see snippet below).

  • Dashboard

  • API

  1. Create a new billable metric;
  2. Click and expand the section Define groups in this billable metric; and
  3. Add groups following the JSON structure below.
{
  "key": "provider",
  "values": ["AWS", "Google", "Azure"]
}

Below is an example of an event with a single group for the billable metric described above:

Event including a group value
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": {
      "transaction_id": "event_001",
      "external_customer_id": "customer_1234",
      "code": "compute",
      "timestamp": 1668461043,
      "properties": {
        "hours": 0.07,
        "provider": "Azure"
      }
    }
  }'

Values are case-sensitive. If you don’t use the exact value when pushing events, they will not be taken into account. Following our example: the expected value is "Azure" and "azure" is an invalid value.

​
Grouping with two keys

It is also possible to define two levels for grouping events. Following our previous example:

In addition to their cloud provider, your customers can select their region.

Therefore, you can define "key": "region" to add a second dimension (see snippet below).

When creating a plan, you will then be able to add a charge for each region available for each provider.

  • Dashboard

  • API

  1. Create a new billable metric;
  2. Click and expand the section Define groups in this billable metric; and
  3. Add groups following the JSON structure below.
{
  "key": "provider",
  "values": [
    {
      "name": "AWS",
      "key": "region",
      "values": ["Europe", "Africa", "Asia"]
    },
    {
      "name": "Google",
      "key": "region",
      "values": ["Europe", "North America"]
    },
    {
      "name": "Azure",
      "key": "region",
      "values": ["North America", "Asia"]
    }
  ]
}

Below is an example of an event including two group values for the billable metric described above:

Event including two group values
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
  "event": {
    "transaction_id": "event_002",
    "external_customer_id": "customer_1234",
    "code": "compute",
    "timestamp": 1668461044,
    "properties": {
      "hours": 0.13,
      "provider": "AWS",
      "region": "Europe"
    }
  }
}'

You can also create billable metrics with dimensions via the API.

​
Edit dimensions

You can edit billable metric groups associated with existing subscriptions. It’s important to note that making changes to these metric groups can have an impact on all plans where this billable metric is defined as a charge. Here’s an example to illustrate the impact of editing a billable metric:

From Payload A: 
{
  "billable_metric": {
    "name": "gigabyte",
    "code": "gigabyte",
    "aggregation_type": "sum_agg",
    "field_name": "total",
    "group": {
      "key": "region",
      "values": [
        "usa",
        "europe",
      ]
    }
  }
}

To Payload B:
{
  "billable_metric": {
    "name": "gigabyte",
    "code": "gigabyte",
    "aggregation_type": "sum_agg",
    "field_name": "total",
    "group": {
      "key": "region",
      "values": [
        "USA",
        "europe",
        "africa"
      ]
    }
  }
}

Note that each group is case-sensitive and has its own group_id, upon which Lago bases its logic. Here’s how Lago handles these changes:

  1. Since "region: europe" remains the same between both payloads;
    its group_id remains unchanged.
  2. As "region: usa" is present in Payload A but not in Payload B;
    its group_id is removed from the billable metric.
  3. As "region: USA" is not present in Payload A but is present in Payload B;
    its group_id will be created in the billable metric.
  4. Similarly, as "region: africa" is not present in Payload A but is present in Payload B;
    its group_id will be created in the billable metric.

When this billable metric is associated with charges, editing it will impact all plans where it is defined.

  • If an existing group_id remains the same (case 1), Lago will retain the group definitions in all associated charges.
  • If an existing group_id is removed from the billable metric (case 2), Lago will remove the group definition in all associated charges.
  • If a new group_id is created in the billable metric (case 3 and 4), Lago will not automatically add the new group to all associated charges; you will need to add them manually.