04 · Plan changes, agents, payment methods and re-authorization (14 Oct 2026) Diagram

The change, its preview (GET /subscription/upgrade-preview/:id), its upgrade or downgrade permission and its charge all use the same quote. It starts from what the customer actually pays (the locked price, or a pushed price once it applies), not the current plan's list rates, in the subscription's own currency.
Upgrade: the price difference for the rest of the period is charged now; an interval change charges the full new price and restarts the period. Plan rates include tax. Downgrade or equal price: stored and applied by billingCycleWorker at renewal, the discount recomputed for the new price. Gateway, currency and country never change.
Reactivation: a CANCELLED subscription renews at the chosen plan, charged less the running discount. The payment applies the plan and sets ACTIVE with a new period starting at the payment; a declined payment leaves it CANCELLED.
Trial conversion: a TRIALING or ENDED free-plan trial becomes ACTIVE when the first paid charge succeeds (period from the payment, trial = cycle 0). A PENDING_SETUP trial is refused. A failed conversion changes nothing.
No card on file, or a Razorpay mandate below the new price: the change rides on the setup as metadata and nothing is written first. Stripe saves the card, then the billing job charges it under a job ID of its own; Razorpay takes the charge and the new mandate in one popup (at least ₹1). The settlement applies the change.

Whenever more agents are onboarded than the new asset count (downgrade, upgrade, reactivation or trial conversion), the customer must keep exactly the new count of the subscription's own agents. The list appears only then, Confirm waits for it to load, and the server refuses any other selection.
Downgrade: the agents not kept are marked pendingRemoval (a “To be removed” badge for the customer and the admin) and removed at the period end. Each new downgrade replaces the marks; withdrawing it clears them.
Change applied once paid: the choice is stored in Subscription.pendingChangeRemovedAgentIds and applied when the payment settles. An unpaid upgrade never alters a scheduled downgrade's selection.
Removal deletes the portal row and writes an asset log entry. The SIEM server is not changed automatically: admins get “Action Required: Remove Agents from the SIEM Server” and remove them by hand.

Payment methods list only the selected subscription's gateway customer. Set default changes that subscription's token. A card added to a subscription with no card at all becomes its default; on a subscription that has one, it stays an extra card until set as default.
Delete refuses the last method and any card used by a subscription that can still be charged or resumed (including PENDING_SETUP and an ACTIVE one set to cancel). A card used only by CANCELLED, ENDED or EXPIRED subscriptions can be deleted and its token is cleared, so renewing sets up a new card.
PENDING_REAUTH and mandate-limit PAST_DUE show payment setup with billing permission. Recovery charges the pushed or locked price minus the running discount and keeps the locked price. A renewal paid late starts its new period on the payment date.
The Stripe billing portal is removed (button, route, service, provider method and the siem:billing:portal action). Cards are managed on the subscription page.
Sources: subscription.service.ts quotePlanChange, upgradeSubscription, startPlanChangeSetup, deletePaymentMethod, markAgentsForDowngrade, recordAgentsForPaidChange; PaymentEventProcessor.ts settlement; UpdateSubscriptionModal.tsx