How to migrate customers to a free plan without losing usage history

To move a customer to a free plan without losing usage history, use Lago's plan change endpoint rather than terminating and recreating the subscription. Terminating generates a final termination invoice and severs the usage history link, which is usually undesirable for a migration.

How plan changes work

Calling POST /api/v1/subscriptions for a customer with an active subscription performs a plan change rather than creating a new subscription. The billing anchor (subscription_at) and billing time carry over to the new plan, and lifetime usage aggregates carry over with it. Wallet credits are unaffected, since wallets belong to the customer rather than the subscription.

Because a free plan has a yearly amount of zero, Lago always classifies the move as a downgrade. The new plan is created as pending and activates at the start of the customer's next billing period, with the customer remaining on their current plan until then. If the change needs to take effect immediately, a manual termination and recreation is required instead.

What to do

Call POST /api/v1/subscriptions with the customer's external_customer_id, the free plan's plan_code, and the existing subscription's external_id. Lago schedules the downgrade for the next billing renewal without generating a termination invoice. The same change can be made in the UI: open the customer's account, click the three-dot menu next to the active subscription, and select "Upgrade / Downgrade plan."

If subscriptions were previously terminated and recreated for past migrations, check those customers' subscription history for gaps and review whether unexpected termination invoices were generated.

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