Pending subscription cancelled when ending_at is set during a downgrade

When a subscription downgrade is scheduled via POST /api/v1/subscriptions, setting ending_at on the current subscription via a subsequent PUT call cancels the pending new subscription instead of transitioning to it as expected. The pending monthly subscription ends up cancelled rather than activating at the transition date.

How it works

When you create a new subscription using an existing subscription's external_id, Lago automatically schedules the plan transition. The current subscription will terminate and the new one will activate at the appropriate date. No additional call is needed to end the old one. The API response confirms this with next_plan_code and downgrade_plan_date fields.

If you then call PUT /api/v1/subscriptions/:external_id to set ending_at on the current subscription, Lago processes that as an explicit termination via the ending_at mechanism rather than through the normal downgrade flow. This bypasses the pending new subscription's activation logic, cancelling it instead.

How to resolve the issue

Remove the PUT /api/v1/subscriptions/:external_id call that sets ending_at from your plan change flow. The downgrade is fully handled by the initial POST call. If the subscription was already cancelled by this pattern, create a new subscription with a new external_id (the old one is bound to the cancelled record) and use a one-off invoice to recover any unbilled period.

How to prevent this from happening again

Do not set ending_at on a subscription that already has a pending plan change. The POST /api/v1/subscriptions response will include downgrade_plan_date confirming that the transition is scheduled automatically.

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