How to change the calculation logic on a billable metric

Last updated: June 19, 2026

Lago locks the aggregation type and field configuration on a billable metric once it is attached to a plan. Editing those fields is not possible in place. The only supported path to change a metric's calculation logic is to delete the existing metric and recreate it with the same code, which starts the metric's event history fresh.

How it works

When a billable metric is linked to a plan, Lago prevents changes to the aggregation type to avoid retroactive billing inconsistencies. Metrics not yet attached to any plan remain fully editable. If you need to change the aggregation type or field name on a live metric, the only option is delete-and-recreate. Filtering logic is the exception. Filters can be edited in place at any time, even on a live metric. Changes propagate to draft invoices and existing subscriptions asynchronously.

Deleting a billable metric has the following consequences:

  • The same metric code can be reused on the new metric.

  • The new metric has no access to historical event data. Events ingested before the deletion are not carried over.

  • Events accumulated in the current open billing period under the old metric are lost. Draft invoices that referenced the deleted metric have those charges removed and are flagged for refresh.

  • Finalized invoices from past periods are not affected.

How to resolve the issue

For production with active subscriptions on anniversary billing (where every subscription has a different billing boundary), there is no single clean cutover moment. The least risky approach is to create the new metric alongside the old one under a different code initially, validate it receives and aggregates events correctly, then perform the swap at a time when current-period revenue exposure is lowest. Ideally, coordinate any metric changes with a billing period boundary for the affected subscriptions.

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