Charges with filters

Define a price for a combination of filters

When a billable metric has defined filters, establish a set of filters to refine an event and assign a price to this combination.

Dashboard
API

Add a charge to a plan (this charge should be associated with a billable metric containing filters);
Add a new filter;
Choose a combination of filters, either specifying a key and its value or simply the key itself (covering all values);
Set a price for this combination of filters; and
Optionally, provide an Invoice display name.

Setting a price for a combination of filter values on a charge in the Lago dashboard — Set a price for a combination of filters

Here is an example of a plan you can create:

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

curl --location --request POST "$LAGO_URL/api/v1/plans" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "plan": {
      "name": "Standard plan",
      "code": "standard_plan",
      "interval": "monthly",
      "pay_in_advance": false,
      "amount_cents": 1000,
      "amount_currency": "USD",
      "charges": [
        {
          "billable_metric_id": "5d387072-e1f2-416f-b981-135c2f177069",
          "invoice_display_name": null,
          "charge_model": "standard",
          "properties": {
            "amount": "2"
          },
          "filters": [
            {
              "values": {
                "region": ["africa"],
                "provider": ["aws"]
              },
              "invoice_display_name": "Africa & AWS",
              "properties": {
                "amount": "1"
              }
            },
            {
              "values": {
                "region": ["__ALL_FILTER_VALUES__"],
                "provider": ["__ALL_FILTER_VALUES__"]
              },
              "invoice_display_name": "Other regions and providers",
              "properties": {
                "amount": "0.5"
              }
            }
          ]
        }
      ]
    }
  }'

Define a default price

When a billable metric has filters defined, set a default price at the charge level to cover all the other combinations of filters not defined in the charge.

Dashboard
API

Add a charge to a plan (this charge should be associated with a billable metric containing filters);
Add a default price; and
Set the amount of this default price.

Setting the default price of a charge that uses filters in the Lago dashboard — Set a default price for a charge handling groups

Here is an example of a plan you can create:

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

curl --location --request POST "$LAGO_URL/api/v1/plans" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "plan": {
      "name": "Standard plan",
      "code": "standard_plan",
      "interval": "monthly",
      "pay_in_advance": false,
      "amount_cents": 1000,
      "amount_currency": "USD",
      "charges": [
        {
          "billable_metric_id": "5d387072-e1f2-416f-b981-135c2f177069",
          "invoice_display_name": null,
          "charge_model": "standard",
          "properties": {
            "amount": "2"
          }
        }
      ]
    }
  }'

If the default price is not set, Lago will automatically define it as 0 based on the charge model.

Editing filter pricing mid-period

When you update a charge’s filter configuration or pricing, for example by adding new filter combinations, changing per-filter rates, or removing the default price, Lago applies the updated pricing rules to all usage in the current open billing period. Fees are not locked at event ingestion time. They are evaluated against the active charge configuration at the time of calculation. This means that events received earlier in the period are repriced under the new configuration, not the one that was active when they were ingested.

Once an invoice is finalized, amounts are permanently locked. Charge configuration changes only affect the current open billing period. To preserve existing pricing on already-received usage, finalize the invoice before updating the charge.

Attributed usage can split a charge by its filters, to show which team or user consumed each filter combination.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Quotes & Order Forms

Invoicing

Payments & Cash Collection

AI Agents and MCP

Data & Analytics

Revenue recognition

Resources

Charges with filters

Define a price for a combination of filters

Define a default price

Editing filter pricing mid-period