Feature Specification: Subscription Payment Failure Grace Period & Dunning Emails

Feature Branch: [001-payment-failure-grace-period]

Created: 2026-07-31

Status: Draft

Input: User description: “stripe setting grace period for 7 days after cycle payment fail, and no auto retry -> need guide on how to setting in stripe; when payment fail, change plan status to PAST_DUE but all feature still be able to use like SETTLED; send 3 mail after payment fail, the mail contain link to the stripe payment page, user click link to change payment method and pay immediately (day 0, day 3, day 6, each only if still PAST_DUE); when user pays manually and succeeds, update plan via webhook and send a payment-completed mail; after day 7, if still unpaid, Stripe automatically cancels the plan and this is reflected via webhook.”

User Scenarios & Testing (mandatory)

User Story 1 - Uninterrupted access during payment grace period (Priority: P1)

A subscriber’s recurring paid-plan payment fails at renewal (e.g., expired or declined card). Instead of losing access immediately, the subscriber’s plan is marked “Past Due” and they continue to use every paid-plan feature exactly as if their payment had settled successfully, for up to 7 days while they sort out their payment method.

Why this priority: This is the core business value of the feature — preventing accidental service interruption and churn from transient card failures, while still creating pressure to resolve payment within a bounded window.

Independent Test: Simulate a renewal payment failure for a paid subscriber and verify the plan status becomes “Past Due” while all previously-available paid features remain fully functional and no features are restricted.

Acceptance Scenarios:

1. Given a subscriber on a paid plan with an active renewal, When the recurring payment fails, Then the plan status changes to “Past Due” and the subscriber retains full access to all paid-plan features.
2. Given a subscriber whose plan is “Past Due”, When they use any feature that was available to them before the failure, Then the feature behaves identically to when their plan status was “Settled”/paid.

---

User Story 2 - Payment failure notification sequence (Priority: P1)

After a renewal payment fails, the subscriber receives up to three emails guiding them to update their payment method and pay immediately: one right away, a reminder 3 days later, and a final notice 6 days later — but only while the plan remains unresolved (“Past Due”). Each email links directly to the Stripe-hosted payment page.

Why this priority: Without a clear, escalating notification sequence, subscribers are unlikely to notice or act on the payment failure before the grace period expires and they are downgraded.

Independent Test: Trigger a payment failure and verify the first email sends immediately; advance time to day 3 and day 6 with the plan still “Past Due” and verify the second and third emails send with correct content and a working payment link.

Acceptance Scenarios:

1. Given a renewal payment just failed, When the failure is recorded, Then the subscriber immediately receives the first notification email containing plan/contract details and a link to the Stripe payment page.
2. Given the plan is still “Past Due” 3 days after the initial failure, When the day-3 check runs, Then the subscriber receives the second (reminder) email.
3. Given the plan is still “Past Due” 6 days after the initial failure, When the day-6 check runs, Then the subscriber receives the third (final notice) email.
4. Given the plan is no longer “Past Due” (payment resolved or plan already canceled) before day 3 or day 6, When the corresponding scheduled check runs, Then the second or third email is NOT sent.

---

User Story 3 - Successful manual payment recovery (Priority: P2)

While “Past Due,” the subscriber clicks the payment link in one of the emails, updates their card details, and pays manually. Their plan is restored to normal paid status and they receive a confirmation email.

Why this priority: Completes the recovery loop so subscribers who take action are clearly confirmed as “safe” and stop receiving further dunning emails.

Independent Test: From a “Past Due” plan, simulate a successful manual payment via the Stripe payment page and verify the plan status returns to paid/“Settled” and a payment-completed confirmation email is sent, with no further dunning emails sent afterward.

Acceptance Scenarios:

1. Given a subscriber’s plan is “Past Due”, When they update their payment method and successfully pay via the Stripe payment page, Then the plan status updates to paid/“Settled” upon confirmation of the payment.
2. Given the payment succeeds, When the status updates, Then the subscriber receives a payment-completed confirmation email containing the amount paid and payment date.
3. Given the payment succeeded on, for example, day 4, When the day-6 scheduled check later runs, Then no further dunning email is sent for that payment failure.

---

User Story 4 - Automatic cancellation after grace period expires (Priority: P2)

If the subscriber has not resolved payment by the end of the 7-day grace period, the paid plan is automatically canceled/downgraded and the subscriber’s local plan record is updated accordingly.

Why this priority: Ensures the grace period has a firm boundary so unpaid subscriptions do not continue indefinitely.

Independent Test: From a “Past Due” plan that received all 3 dunning emails, let the grace period lapse without payment and verify the plan is automatically downgraded and the subscriber’s records reflect the cancellation.

Acceptance Scenarios:

1. Given a subscriber’s plan has been “Past Due” for 7 days with no successful payment, When the grace period expires, Then the plan is automatically canceled and the subscriber is downgraded to the free plan.
2. Given the automatic cancellation occurs, When the cancellation is processed, Then the subscriber’s local plan/subscription record is updated to reflect the downgrade without requiring manual admin action.

---

Edge Cases

• What happens if the subscriber updates payment and pays successfully on the exact day a scheduled reminder (day 3 or day 6) is also due to run? The system must not send a dunning email once status is no longer “Past Due”, regardless of timing overlap.
• What happens if a subscriber manually cancels their own plan while it is “Past Due” (before day 7)? No further dunning emails should be sent for that failure.
• What happens if the payment-completed confirmation and the automatic-cancellation event arrive close together near the end of day 7 (race condition)? The system must apply whichever outcome the payment platform confirms last and must not both restore and cancel the plan for the same failure.
• What happens if a subscriber has multiple consecutive renewal failures (e.g., grace period restarts each billing cycle)? Each new payment failure starts its own independent 7-day/3-email cycle.
• What happens if an email fails to deliver? The scheduled next-step logic (day-3/day-6 checks and eventual auto-cancellation) must not depend on prior email delivery having succeeded.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST support a 7-day grace period after a subscription renewal payment failure, during which no additional automatic payment retry attempts are made.
• FR-002: When a renewal payment fails, System MUST change the subscriber’s plan status to “Past Due” while keeping all paid-plan features fully usable, identical to the “Settled” (fully paid) status.
• FR-003: System MUST send the 1st payment-failure notification email immediately upon detecting the payment failure.
• FR-004: System MUST send the 2nd payment-failure notification email exactly 3 days after the initial failure, and only if the plan status is still “Past Due” at that time.
• FR-005: System MUST send the 3rd payment-failure notification email exactly 6 days after the initial failure, and only if the plan status is still “Past Due” at that time.
• FR-006: Each of the 3 notification emails MUST include the subscriber’s contract details (plan name, contract period, fee amount), the payment result, and a link that takes the subscriber directly to the Stripe-hosted payment page to update their payment method and pay immediately.
• FR-007: System MUST NOT send the 2nd or 3rd notification email if the plan status has already changed away from “Past Due” (payment resolved or plan already canceled) before the scheduled send time.
• FR-008: When the subscriber successfully completes a manual payment while “Past Due,” System MUST update the plan status back to paid/“Settled” upon receiving confirmation of that payment from the payment platform.
• FR-009: When the manual payment succeeds, System MUST send a payment-completed confirmation email containing the plan/contract details, amount paid, and payment date.
• FR-010: If the subscriber has not completed payment by the end of the 7-day grace period, the plan MUST be automatically canceled/downgraded to the free plan, with no manual intervention required.
• FR-011: System MUST update the subscriber’s local plan/subscription record in response to payment-platform notifications (payment failed, payment succeeded, subscription canceled) rather than relying on the subscriber or an admin to trigger the update.
• FR-012: All notification and confirmation emails MUST be delivered automatically (system-generated, no-reply) without requiring any manual action by staff.

Key Entities

• Subscription/Plan: The subscriber’s paid-plan enrollment; key states are Active/Settled (fully paid), Past Due (payment failed, within grace period, full access retained), and Canceled/Free (grace period expired or subscriber canceled).
• Payment Failure Event: Represents one renewal payment failure occurrence; tracks the failure date/time (used to compute the day-3 and day-6 email schedule and the 7-day cancellation boundary) and which of the 3 notification emails have been sent.
• Notification Email: One of four templated system emails sent to a subscriber — 1st failure notice, 2nd reminder, 3rd final notice, and payment-completed confirmation — each containing contract details and, where applicable, a payment update link.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of subscribers whose renewal payment fails retain uninterrupted access to every paid-plan feature throughout the entire 7-day grace period.
• SC-002: The first payment-failure notification email is sent within minutes of the failure being detected, for 100% of failure events.
• SC-003: The 2nd and 3rd notification emails are sent only when the plan is still unresolved, with 0% of these emails sent after a subscriber’s payment has already succeeded or their plan already canceled.
• SC-004: 100% of subscribers who successfully pay manually during the grace period have their plan status restored and receive a confirmation email without needing to contact support.
• SC-005: 100% of subscribers who do not resolve payment within 7 days are automatically moved to the free plan without any manual admin action.

Assumptions

• “Cycle payment fail” refers to a failed automatic renewal charge on an existing paid subscription (not the subscriber’s very first sign-up payment).
• The Stripe subscription settings (grace period length, disabling automatic retries, and automatic cancellation after the grace period) are configured directly in Stripe’s dashboard/billing settings rather than being a piece of software configurable in-app; this is treated as an operational setup dependency for this feature rather than a functional requirement to build.
• “Day 3” and “Day 6” are measured as 3 and 6 full days elapsed from the timestamp of the initial payment failure for that billing cycle.
• The Stripe-hosted payment page referenced in the emails is the existing customer payment/portal link already available for this subscription (e.g., a hosted invoice or billing portal page), not a newly built in-app payment page.
• All four email templates (1st notice, reminder, final notice, payment-completed confirmation) use the exact Japanese subject lines and body copy provided in the feature request, with template placeholders filled from the subscriber’s contract data.
• If a subscriber has multiple past-due billing cycles over time (e.g., resolves one failure, then fails again on a later renewal), each failure is treated as an independent grace-period cycle with its own 3-email schedule.
• Downgrading to the free plan reuses the existing free-plan downgrade behavior already used elsewhere in the system (e.g., existing trial-to-free downgrade), rather than requiring a new kind of “free plan.”