Why a customer's external_id can't be changed once it has subscriptions

Lago does not allow editing customer.external_id after a customer has billing activity such as subscriptions, invoices, or ingested events. In this state the customer record is non-editable and the external ID is locked. The reason is that events are aggregated by customer_external_id (together with subscription_external_id), so changing the ID would break the existing event history and produce an incorrect usage summary.

How the external_id works

The external_id is the stable key Lago uses to attach everything you send to a customer. When events are ingested and usage is computed, Lago aggregates those events by the customer's external ID and the subscription's external ID. The ID is therefore not just a label — it is part of how usage is joined to the right customer and subscription.

A customer can only be edited while it has no billing activity attached. Internally this is gated by customer.editable?: it returns true for a clean customer and false once activity exists.

Field reference

customer.editable? is the check that determines whether the external ID (and other identifying fields) can still be modified. It returns true only when all of the following are true: no subscriptions, no applied add-ons, no invoices, no applied coupons with a currency set, and no wallets.

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