03 · Renewals, retries, grace and expiry (billingCycleWorker, retryPaymentWorker, lifecycleWorker, daily sweeps, 14 Oct 2026) Diagram

Renewal order of operations

Billing, scheduled retries and manual retries validate company country against the stored gateway and currency before charging.
Job id billing-cycle-{sub}-{n}; skipped if status or cycle number does not match; cycle 0 runs for UNPAID and for PAYMENT_FAILED (a new card saved for a failed first charge)
Each renewal charge attempt is scheduled at currentPeriodEnd; an early queued job for an ACTIVE subscription is delayed to that boundary. A plan-change charge (trial, upgrade or reactivation after a card setup) is its own job with its own ID, so it is not absorbed by the cycle's delayed renewal job.
Cancel flag at period end: beginCancellationGracePeriod writes CANCELLED with an expiry date, grace warnings and the final job, and sends 'Your Paid Access Has Ended'. The midnight sub-finalization sweep uses the same function.
Scheduled downgrade applied before charging, the discount recomputed for the new price (percentage follows, fixed stays); the agents marked pendingRemoval leave the portal and admins are emailed to remove them from the SIEM server by hand
Charge = resolveCycleChargeAmount: max(cycle price less running discount, 0); the cycle price is the pushed price once its cycle is reached and the customer was emailed, else lockedPriceAmount; plan rates already include tax
Stripe uses the supplied idempotency key. Razorpay claims a unique durable attempt per subscription cycle before creating an order or debit; pending outcomes are checked against the original order, and only a confirmed failure allows a new attempt.

Gates

$0 cycle settles internally through PAYMENT_SUCCEEDED (no gateway)
No provider or card (for example a migrated customer who has not added one): PAST_DUE, the grace period is started with its real deadline (expiryDate), and the customer is emailed that no payment was taken, the amount due and the days left to add a card. A missing locked price takes the same recovery.
Razorpay with a pushed price above mandateMaxAmount: PENDING_REAUTH, 'Payment Failed - Action Required', grace
Redis charge-in-flight:{sub} has a 24h TTL that Stripe reconciliation keeps extending while it still holds the lock. RazorpayChargeAttempt persists beyond Redis and across processes; unknown outcomes return pending and refuse another debit.
Existing Stripe customers are moved by scripts/stripe-cutover.ts (ACTIVE until their paid-through date, or PAST_DUE with grace); the first card they add becomes the default. They do not pass through PENDING_REAUTH.
If a process stops before its Razorpay order ID is persisted, the pending attempt blocks another debit; no automatic recovery is implemented.

Retries, grace, reminders and sweeps

The chain is driven by failure events: renewal failure schedules attempt 1; attempt n failure schedules n+1; at most 3, 3 days apart
Only temporary reasons are retried (retryableFailure.ts): insufficient funds, balance or daily limits, bank, network or gateway errors; expired, lost or stolen card, wrong details, authentication and mandate limit are not
Manual retry charges the same cycle amount and re-reads the subscription after taking the charge lock, so it never charges a cycle a scheduled retry just settled. Its failure schedules nothing; the retry worker skips a job whose cycle is no longer current.
A renewal paid while PAST_DUE or PENDING_REAUTH, inside the grace period, starts its new period on the payment date and moves the renewal date. An on-time renewal keeps starting at the old period end.
Grace length from STRIPE_*_GRACE_PERIOD_DAYS by interval (free trial 7 days). Every grace start sets expiryDate to the deactivation date, so 'Data Deletion in N Day(s)' states the real date.
final-deactivation: ENDED, PAST_DUE, PENDING_REAUTH or CANCELLED become EXPIRED, portal agents are deleted, customer and admin emailed. EXPIRED cannot be recovered.
Renewal reminders (7, 3 and 1 day before the period end) are rendered when they are sent: renewal date and the amount that will be charged, with the running discount, a pushed price or a scheduled downgrade; 'add a payment method' for a subscription without a card; 'expires, resume' when set to cancel.
Daily: 00:00 sub-finalization (trials end at the claim deadline and expire at trialEnd + 7 days; a paid cancel-flag row past period end goes through the CANCELLED grace function); 00:15 abandoned-cleanup (excludes coupon bookings and in-flight signup payments; other UNPAID/PAYMENT_FAILED rows older than 25h with a provider, except a Razorpay signup whose order can still be paid); 03:00 reminder-sync; 02:30 expired-agent sweep; hourly missed-renewal reconciliation.

Fixed since the 6 Oct audit

D50: a late paid renewal starts its period at the payment date. D42: card signups now get reminders. D55: grace warnings state the real deadline. D20: the midnight sweep starts the full grace. D25: a renewal without a card emails the customer.
D54: a Stripe charge with an unknown outcome keeps its lock; task:stripe-charge-reconcile resends it with the same idempotency key, keeps checking a payment still processing after 24 hours, and extends the lock meanwhile.
Definitive synchronous charge failures use the shared failure processor; pending or unknown outcomes do not free coupon capacity.