---
title: "Verify a failed renewal follows the documented grace period"
description: "Trigger a sandbox renewal failure and check payment warnings, grace-period access, eventual restriction, and billing state at controlled lifecycle points."
canonical_url: "https://vostride.com/agent-library/billing-subscriptions/failed-renewal-grace-period.md"
md_url: "https://vostride.com/agent-library/billing-subscriptions/failed-renewal-grace-period.md"
content_kind: "recipe"
topic: "billing-subscriptions"
---

# Verify a failed renewal follows the documented grace period

Trigger a sandbox renewal failure and check payment warnings, grace-period access, eventual restriction, and billing state at controlled lifecycle points.

## Risk

Payment failure handling often spans several days and states. A useful regression checks the configured grace policy with sandbox time controls and avoids treating a pending invoice as either a successful charge or immediate cancellation.

## Fixtures

- A sandbox customer whose next renewal payment is configured to fail through provider test fixtures.
- A known grace duration and product rules for warning banners, retries, and restricted features.
- A controlled billing clock and hooks for invoice attempts, subscription status, and entitlement deadlines.

## Steps

1. Advance the active fixture subscription to renewal and verify the sandbox invoice reports the expected failed payment outcome.
2. Open Billing and verify a clear payment-action warning with the correct amount and an accessible update-payment route.
3. Before the grace deadline, verify the paid fixture capability remains available if policy permits it.
4. Advance beyond the documented grace boundary without fixing payment and verify the application applies the intended restriction or cancellation state.
5. Inspect invoice attempts and entitlements to confirm no failed attempt was marked paid and all lifecycle dates agree with the configured grace policy.

## Expected results

- Failed renewal produces an unpaid invoice and the correct user-facing action state.
- Access during grace matches the documented allowance.
- After grace, restrictions occur at the intended boundary without recording a nonexistent successful payment.

## False-pass traps

- A provider decline response does not prove the application processed the failure event.
- Repeated uncontrolled retries can create ambiguous billing attempts and obscure which lifecycle event changed access.

## Cleanup

- Cancel the fixture subscription, restore its payment fixture, and clear clock overrides.

## Use with agent-qa

Adapt this test design to your application's acceptance criteria and configured target using the [recipe execution guide](/agent-library/software-factory/turn-a-recipe-into-an-agent-qa-test.md). External fixture setup and non-UI checks require your own supported hooks or test tooling. Validate the authored test, execute it, and inspect the completed evidence; this recipe is not a recorded test result.

## References

- [agent-qa test](/docs/agent-qa/configuration/test.md)
- [agent-qa hooks](/docs/agent-qa/guides/hooks.md)
- [agent-qa auth state](/docs/agent-qa/guides/auth-state.md)

- [Billing and subscription QA recipes](/agent-library/billing-subscriptions.md)
- [Software factory QA library](/agent-library.md)