Job flow 2 · task:billing-cycle (plan change paid with a just-saved Stripe card) Diagram

What each step does

Queued by: Stripe setup_intent.succeeded (TOKEN_SAVED) whose setup carried a plan change — trial conversion, an upgrade with no usable card, a reactivation with no card; and by upgradeSubscription directly for a Stripe reactivation with a card on file. Job ID billing-cycle-<sub>-<cycle>-<reason> (trial_upgrade, upgrade, reactivation) so the cycle's delayed renewal job does not swallow it. Delay 0.
Still valid: trial_upgrade needs the current plan still free and status TRIALING or ENDED; upgrade needs ACTIVE; reactivation needs CANCELLED; the subscription's cycle must equal the job's.
Amount ≤ 0 (a running discount covers it, or an upgrade proration under 0.50) → internal PAYMENT_SUCCEEDED with the change attached; the change is applied without a gateway call.
Charge: trial conversion and reactivation take the charge lock; an upgrade proration does not. Idempotency key sub_<id>_<reason>_<cycle>_<plan>_<assets>_<interval>_<token>. Unknown outcome → stripe-charge-reconcile.
Paid (webhook): trial → ACTIVE, plan applied, period starts now, paid cycle 1, next renewal cycle 2, trial and grace jobs removed, 'Payment Successful' + PDF, admins 'Payment Received'. Reactivation → ACTIVE, chosen plan, new period from payment, cycle + 1, 'Payment Successful'. Upgrade → plan, assets, price applied; changed interval restarts the period and replaces the renewal job; 'Subscription Upgrade Details'. Agents not kept are deleted and admins emailed.
Declined: lock released (trial/reactivation), email 'Payment Failed - Action Required' saying the change did not happen; status, plan and period unchanged; no grace, no retry.