feat(multi-billing-entity): move subscription

[aquinofb]

Summary

Operators can now move an active subscription to a different billing entity through a normal PATCH /api/v1/subscriptions/:external_id request, instead of having to terminate and recreate it. From the next billing cycle on, invoices for that subscription land under the new entity (using its number prefix and sequence); invoices already generated stay where they were.

The change is gated behind the multi_entity_billing feature flag, so single-entity organizations see no behavior change at all.

What changed

Concern	Before	After
Moving a subscription to another billing entity	Terminate and recreate	PATCH with billing_entity_id or billing_entity_code
Where invoice rows read their billing entity from	customer.billing_entity	subscription.billing_entity (falls back to customer's)
Where fees read their billing entity from	subscription.customer.billing_entity_id	subscription.billing_entity_id (falls back to customer's)
Subscriptions with NULL billing_entity_id (every row in prod today)	Stamped with customer's entity	Same; the column fallback keeps stamping byte-identical
Customer with multiple subs on different entities billed together	Not reachable	Returns a mixed_billing_entities validation failure; never produces a mixed invoice
Feature flag off	Param wasn't accepted	Param is silently ignored, matching the create-side convention

How the resolver works

Subscriptions::UpdateService resolves the entity inline. It accepts either an id or a code on the same request; if both are sent, the id wins. Unknown values return a 404 with billing_entity_not_found. Cross-organization references resolve to "not found" because the lookup is scoped to the subscription's organization.

For the read side, every fee and invoice writer now prefers subscription.billing_entity_id || subscription.customer.billing_entity_id. Because every existing subscription row has a NULL override, the fallback path is taken and the behavior is identical to today. Once an operator flips the column, the next invoice and its fees follow.

The one read site that intentionally stays on subscription.customer.billing_entity is the previous-period proration lookup in Fees::FixedChargeService, because legacy paid fees were written against the customer's entity and the query needs to match them.

Out of scope

The subscription.updated webhook payload doesn't surface the new billing_entity_id yet; that lives with the serializer and OpenAPI work. Batched billing across mixed-entity subscriptions returns a validation error today; the proper fix is to split the batch upstream in OrganizationBillingService and is deferred.

Test plan

• Seed an organization with multi_entity_billing in feature_flags, plus two billing entities us (default) and eu. Seed a customer under us and an active subscription on a monthly recurring plan.
• PATCH /api/v1/subscriptions/:external_id with { subscription: { billing_entity_code: "eu" } }. Expect 200 and verify the subscriptions row's billing_entity_id now points at eu; the customers row is unchanged.
• Force the next billing cycle (move the clock to the calendar boundary or invoke BillSubscriptionJob directly for the subscription). Verify the resulting invoice's billing_entity_id is eu, its number draws from eu's sequence and prefix, and any previously-generated invoices are untouched.
• Toggle multi_entity_billing off on the organization. PATCH the subscription again with billing_entity_code: "us". Expect 200 and no change to the row.
• Re-enable the flag. PATCH with billing_entity_id set to a random UUID. Expect 404 with code: "billing_entity_not_found". PATCH with billing_entity_id referencing an entity from a different organization. Expect the same.
• Create a second subscription on the same customer and PATCH it to eu, leaving the original on us. Trigger their next billing day. Expect a validation failure with billing_entity: ["mixed_billing_entities"] rather than a mixed invoice.

[mariohd]

Looks good