05 · Subscription status: every writer, access by status and rejected transitions (14 Oct 2026) Diagram

subscriptionRepository.updateStatus runs validateStatusTransition and throws on a rejected move
Callers: SubscriptionService, billingCycleWorker, lifecycleWorker, task:sub-finalization. PaymentEventProcessor's first-charge, renewal, reactivation, trial-conversion and failure writes call validateStatusTransition inside the settlement transaction.
A paid plan change never writes status before its payment settles. Admin activation rollback writes PENDING_SETUP through updateWhere without the check.
Abandoned-cleanup deletes UNPAID and PAYMENT_FAILED rows older than 25h with no coupon, no signup payment in flight and a provider. Customers cannot delete a subscription.
The PAID status no longer exists

ACTIVE, TRIALING: SIEM, team (IAM), profile, subscription, wallet with top-up
PENDING_SETUP, PAST_DUE, PENDING_REAUTH, CANCELLED, ENDED: no SIEM; team, profile, subscription and billing, wallet view
UNPAID, PAYMENT_FAILED, EXPIRED, no subscription: profile and subscription (buy new) only
One rule drives the server route gate, the IAM context sent to the client and the client route guard. Notifications and /iam/me are open to every status.

PAST_DUE or PENDING_REAUTH paid inside the grace period: ACTIVE, and the new period starts on the payment date
CANCELLED renewed in its grace period: ACTIVE with the chosen plan, a new period starting at payment, cycle +1. A declined payment leaves it CANCELLED.
A migrated customer with no card: ACTIVE until the paid-through date; the first card added becomes the default; no card by renewal means PAST_DUE with the normal grace period
EXPIRED cannot be recovered

A TRIALING or ENDED free-plan trial converts in place. The chosen plan is applied only when the first paid charge succeeds; then the subscription is ACTIVE, the paid period starts at the payment (unused trial days are not carried), the trial is cycle 0, the payment cycle 1 and the next renewal cycle 2.
A trial still in PENDING_SETUP awaits admin activation and is not offered the upgrade, in the portal or the API
A declined or abandoned conversion leaves the trial unchanged (no PAYMENT_FAILED). If the new asset count is below the onboarded agents, the customer chooses which to keep; the others leave the portal when the payment settles and admins are emailed to remove them from the SIEM server.
Admins receive the Payment Received email for a conversion, since there is no activation step

Claim starts the deadline: claim, PENDING_SETUP, ENDED, EXPIRED even if no agents are onboarded
Admin activates an onboarded free trial as TRIALING before its claim deadline; activation preserves trialStart, trialEnd and reminders
A 14-day trial claimed on day 0 ends on day 14; activation on day 3 leaves 11 days. Its 7-day grace ends on day 21.
Expired claim deadlines cannot be extended; free plans cannot be activated as ACTIVE

export (before the schema push): saves each Stripe subscription's status, paid-through period and legacy invoice and payment IDs, then cancels it at Stripe with no proration and no final invoice
apply (after the push and seeds): Stripe active becomes ACTIVE until its paid-through date at cycle 1; past_due or unpaid becomes PAST_DUE with grace. Price comes from the seeded plan rate in its own currency; legacy IDs are copied back; the customer is emailed to add a card.
Migrated customers do not pass through PENDING_REAUTH. A missing country defaults to IN, with the gateway and currency written with it.