feat(multi-billing-entity): support billing entity on subscription upgrade

[aquinofb]

Context

Multi-billing-entity support has been rolling out across the API a slice at a time. Subscription create landed in #5467 and wallets in #5471. The upgrade path was the next obvious gap: if you'd explicitly bound a subscription to a non-default entity (say eu instead of the customer's default us), upgrading the plan silently dropped that binding. The new subscription ended up with billing_entity_id NULL and quietly inherited the customer's default at billing time. The billing_entity_id and billing_entity_code params that already work on create were silently ignored on upgrade, so operators couldn't re-bind during an upgrade either.

The same gap was hiding inside pending-subscription promotion: when an operator raised a plan's amount above the previous one (via Plans::UpdateService or Plans::UpdateAmountService), the pending subscription got promoted through PlanUpgradeService, and the binding was lost the same way.

Description

There are two moving parts. The resolution rule (read params, gated by multi_entity_billing, scoped to the customer's organization, not-found error on unknown id/code) is the same one CreateService already had inline. I extracted it into a small shared concern, Subscriptions::Concerns::BillingEntityResolutionConcern, so create and upgrade now share a single source of truth.

The new behaviour on upgrade is straightforward: resolve the entity from params if the flag is on, else carry over current_subscription.billing_entity_id. The carry-over reads the raw FK column rather than the Subscription#billing_entity reader, because the reader would otherwise materialise the customer's current default and freeze it into the new row, collapsing the "inherit at billing time" semantic. The carry-over runs regardless of the feature flag, so an explicit binding made while the flag was on survives even if the flag is later toggled off; on single-entity orgs every FK is NULL, so this branch is a no-op for them.

The two pending-promotion paths (Plans::UpdateService and Plans::UpdateAmountService) needed no code change. They already call PlanUpgradeService, and once upgrade does the carry-over, those inherit the behaviour. Two new specs confirm it end-to-end.

Behaviour by scenario

Scenario	Before	After
Flag ON, no param, current sub bound to eu	new sub billing_entity_id = NULL (binding lost)	new sub bound to eu
Flag ON, no param, current sub NULL	NULL (inherit customer default at read time)	NULL (inherit customer default at read time)
Flag ON, billing_entity_code: us, current sub bound to eu	param ignored, new sub NULL	new sub bound to us
Flag ON, unknown billing_entity_code	param ignored, new sub NULL	not_found_failure(resource: "billing_entity")
Flag OFF, current sub bound to eu	new sub NULL (binding lost)	new sub bound to eu (carry-over independent of flag)
Pending-promotion via Plans::UpdateService / UpdateAmountService	new sub NULL	new sub keeps previous binding

How to try locally

Spin up a customer on an org with multi_entity_billing enabled and at least two billing entities. Call them eu and us.

1. Create a subscription bound to eu:

   curl -X POST http://localhost:3000/api/v1/subscriptions \
     -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
     -d '{"subscription":{"external_customer_id":"cust_1","external_id":"sub_1","plan_code":"starter","billing_entity_code":"eu"}}'

2. Upgrade the plan with no billing_entity_* in the body:

   curl -X POST http://localhost:3000/api/v1/subscriptions \
     -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
     -d '{"subscription":{"external_customer_id":"cust_1","external_id":"sub_1","plan_code":"growth"}}'

3. Check the new active subscription's billing_entity_id. It now matches the previous one. Before this change it would have been NULL, and the next invoice would have been numbered under the customer's default entity.

To exercise the explicit-override path, replace the second body with "billing_entity_code":"us". The new subscription binds to us, and the termination invoice for the previous subscription stays under eu.

The full test suite for the change:

lago exec api bundle exec rspec \
  spec/services/subscriptions/plan_upgrade_service_spec.rb \
  spec/services/subscriptions/create_service_spec.rb \
  spec/services/plans/update_service_spec.rb \
  spec/services/plans/update_amount_service_spec.rb

226 examples, 0 failures.