Job flow 1b · task:billing-cycle — charge and outcome Diagram

What each step does

Locked price missing → status PAST_DUE and startPaymentGracePeriod (expiryDate, grace-warn-3d/1d, grace-final). A missing price is never treated as a free cycle.
Amount = cycle price (pendingPriceAmount once its cycle is reached and the customer was emailed, else lockedPriceAmount) − running discount (while discountCyclesUsed < discountCyclesTotal; null = forever). ≤ 0 → PaymentEventProcessor gets an internal PAYMENT_SUCCEEDED (externalId internal_zero_<sub>_cycle_<n>, 'Fully discounted — no payment taken'); period advances like a paid renewal.
No provider or card → PAST_DUE + grace + email 'Payment Failed - Action Required': no payment method on file, amount due, days left to add one.
Razorpay ceiling: only when a pushed price applies. Price above mandateMaxAmount → PENDING_REAUTH, paymentFailureSubReason PRICE_EXCEEDS_MANDATE, grace started, email asking to re-authorize. The old price is not charged.
Lock + charge: Redis key charge-in-flight:<sub> (NX, 24 h). Held by another charge → job ends; that charge settles the cycle. Cycle 0 also claims the single signup debit (signupPaymentInFlight). chargeOffSession with idempotency key sub_<id>_cycle_<n>_<token> and metadata internalSubscriptionId, billingCycleNumber, retryAttempt 0, discountAmountApplied.
Declined at once → PAYMENT_FAILED event processed now: cycle 0 → PAYMENT_FAILED (Stripe checkout closed, coupon slot released, one email); cycle ≥ 1 → PAST_DUE, first failure emails and starts grace, retry-payment +3 days if the reason is temporary. Job marked failed in Bull Board.
Success or pending → nothing written here; the gateway webhook settles it (renewal: ACTIVE, period from old end + interval, cycle + 1, invoice, settlement follow-up). Stripe unknown outcome → lock kept, stripe-charge-reconcile queued.