Per-instance billing: volume pricing with billable metric filters and group keys

To bill compute or infrastructure usage per instance (where each instance has both static attributes like region and size, and dynamic identifiers like replica number or instance ID), combine a Sum billable metric, Volume pricing, and pricing_group_keys. This produces one invoice line item per unique instance instead of a single aggregated line per plan.

How it works

Lago uses two mechanisms to split usage into separate line items. Filters on the billable metric capture static, predefined dimensions such as region and size; these become filterable axes on the charge. pricing_group_keys on the charge capture dynamic values passed in the event payload, such as replica number and instance identifier. Lago creates one fee and one invoice line item for each unique combination of filter values and group key values. The order group keys appear in the line item description follows the order they were defined on the charge; to change it, recreate the charge with the keys in your preferred sequence. For static dimensions, set human-readable labels with invoice_display_name on each filter value to avoid exposing raw identifiers like us-east-1 on customer invoices.

What to do

1. Create the billable metric with aggregation type Sum, and add region and size (or your equivalent static dimensions) as filters.

2. Configure the charge on the plan with pricing model Volume, filtered by those same dimensions, with your pricing tiers defined and pricing_group_keys set to ["replica", "instance_identifier"] (or your equivalent dynamic dimensions).

3. Send one event per replica per billing interval, not aggregated across replicas, with all filter and group key fields present in properties:

{
  "transaction_id": "evt_unique_id",
  "external_subscription_id": "sub_abc123",
  "code": "compute_usage",
  "properties": {
    "seconds": 3600,
    "region": "us-east-1",
    "size": "flex-1vcpu-1gb",
    "replica": "1",
    "instance_identifier": "6d5e8db1-7fc0-49c7-bd16-67a0e2b04a05"
  }
}

Things to plan for

If a group key value changes mid-billing period, for example an instance is renamed, events before and after the change are attributed to different line items, potentially splitting what the customer considers one resource into two charges. Customers with many instances will also generate a large number of invoice line items; plan for this in your invoice template and consider a summary view for high-volume customers.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.