How Do Grace Periods and Payment Retries Work for Failed Subscription Renewals?

When Does a Grace Period Apply?

A grace period is triggered when an auto-renewal payment attempt fails. During the grace period, the subscriber typically keeps access while Piano retries the payment according to the term's grace period configuration. This behavior is designed to reduce passive churn from temporary payment issues such as expired cards, insufficient funds, fraud checks, or carrier billing limits.

A grace period generally does not apply when a subscriber:

• Manually cancels a subscription, or

• Turns off auto-renewal before the renewal payment fails

How Grace Periods Start

Grace periods are aligned to the subscription's scheduled renewal:

• The grace period start date is based on the subscription's next bill date (the scheduled renewal date), not necessarily the timestamp of the first decline.

• In practice, Piano may begin renewal processing hours before the actual scheduled renewal time. This can produce failed attempts earlier than the next bill date, making it appear as though the grace period starts in the future.

Time zone note: If grace period or billing timestamps appear inconsistent, verify you are comparing dates in the same time zone. Reporting tools and exports can format timestamps differently depending on viewer or report settings.

What You Will See in the Dashboard

During a grace period, Piano may:

• Extend the subscription's access/expiration display as if the renewal succeeded, so the subscriber does not immediately lose access.

• Show a next billing attempt date that reflects the upcoming retry schedule.

This can make the subscription appear active far into the future even though the last renewal attempt failed. Access is revoked only if payment is not recovered by the end of the configured grace period.

Reporting impact: Because access may remain active through grace, subscriber counts and "active" status reporting can reflect subscribers as active longer than expected. Ensure internal teams understand how grace affects activity reporting.

Configuring the Grace Period

Grace periods are configured per term in the Dashboard. The setting is typically found under churn-prevention or payment-term settings, depending on your setup.

Key constraints:

• You can change the grace period duration, but you cannot change the number of retry attempts Piano performs.

• The grace period cannot exceed the billing period of the term (e.g., a monthly term typically cannot have a grace period longer than 31 days).

• Setting a grace period to 0 effectively means no grace — access can be revoked immediately after failure and retries may be limited.

• Very long grace periods can lead to unexpectedly extended access and repeated billing attempts. If you see access seemingly extended by unusually long periods, review term configuration.

Payment Retry Logic During Grace Period

Piano's retry behavior is driven by the grace period setting on the term.

Grace Period = 0 (No Grace Period)

• Piano attempts the charge up to 3 times on the renewal day (the same day the subscription is due to renew).

• If all attempts fail, the subscription is not renewed.

Grace Period > 0

• Piano attempts the charge again in 5-day increments throughout the grace period.

• The final retry occurs on the last day of the grace period.

• Retries are capped at up to 6 attempts over a 30-day window. Timing is adjusted if the grace period is not a multiple of 5, or if it is longer than 30 days, in which case the final attempt aligns to the last day of the grace period.

During grace, Piano is designed to attempt to collect payment for each missed billing period. This is expected behavior, not a bug. Subscribers who update their payment details late in the grace period may be charged for missed periods.

Retry Cadence Examples

Retry timing is derived from the grace period duration. The following examples illustrate how retries are scheduled:

Example: 19-Day Grace Period

If the renewal attempt fails on day 0, retries occur on:

Changing the Grace Period While Subscribers Are Already in Grace

If you change the grace period setting while subscribers are already in grace (for example, from 7 to 10 days):

• Subscribers already in grace will follow the new retry schedule from that point forward.

• The grace period starting point does not move — it remains tied to the original renewal failure date.

• Retries that would have happened before the change (and are already in the past) are not retroactively re-run.

Example: If a subscriber is on day 6 of a 7-day grace period and you extend it to 10 days, the next retry will follow the 10-day schedule (for example, day 10), not day 7.

Billing Cycle Behavior

Grace periods are intended to recover payment without changing the subscription's underlying schedule.

• The subscription's renewal date remains based on the original subscription/renewal anniversary, not the day the payment method is updated.

• A successful payment during grace typically keeps the subscriber aligned to the original renewal cadence.

This can lead to scenarios such as a subscriber paying late within grace, but the next renewal still occurring on the original schedule. In some cases (e.g., shorter cycles like 4-week terms), two successful charges may fall within the same calendar month.

What Happens When the Subscriber Updates Their Payment Method

If the subscriber updates their card during the grace period:

• The next scheduled retry will use the updated payment method.

• Piano does not necessarily charge immediately upon card update — it generally waits for the next retry run.

• The subscriber may see a small authorization/verification charge on the new card when it is added.

If the grace period ends without a successful charge:

• Access is revoked and the subscription expires (often reflected as expired with error or payment failed in reporting).

• Further automatic retry attempts stop.

• The subscriber typically needs to repurchase to regain access.

Email Notifications During Payment Failure and Grace Period

Piano can send automated emails during the retry window. Common notification types include:

{{#if grace_period}}{{grace_period}}{{else}}30{{/if}} days.

Confirm your email tooling supports the {{grace_period}} variable; otherwise it may render blank. Also note that access_expiration_date may not accurately reflect the grace period in a way that is clear to subscribers, so explicit grace-period messaging is preferred in renewal-failure notifications.

Webhooks and Events

During the grace period workflow, Piano emits the following webhook events for your integrations. Each event carries grace-period-related fields in its payload, including is_in_grace, grace_period_start_date, grace_period_length, and failure_counter.

Grace Period Started

When a subscription enters a grace period upon a failed auto-renewal, two webhooks are sent:

• subscription_updated / subscription_grace_period_started — Sent when the subscription enters the grace period. For shared subscriptions, a corresponding shared_access_modified / subscription_grace_period_started event is also sent for each child access.

• access_modified / grace_period_extension_on_renewal — Sent when Piano grants the subscriber additional days of access during the grace period. This fires instead of the standard subscription_auto_renewed access modification event.

Payment Failure During Grace

Each failed payment attempt during the grace period — including the initial failure that starts grace, all intermediate retries, and the final attempt — triggers:

• subscription_renewal / subscription_auto_renewed_failure — Sent for every unsuccessful auto-renewal attempt. This covers all cases: immediate expiration when there is no grace period, the first failure that starts a grace period, all intermediate retry failures, and the final failure that ends the grace period.

To determine which attempt corresponds to the final failure, inspect the failure_counter field in the payload. This field tracks the cumulative number of payment failures for the subscription and increments with each unsuccessful attempt.

Grace Period Ended Successfully

When a payment succeeds and the subscription exits the grace period, Piano sends:

• subscription_updated / subscription_grace_period_ended — Sent when the subscription successfully exits the grace period upon automated or manual renewal.

• subscription_renewal / subscription_auto_renewed — Sent to confirm the successful auto-renewal, including renewals that complete after a grace period.

Subscription Expired After Grace

If all retry attempts are exhausted without a successful payment, Piano sends:

• access_revoked / subscription_auto_renewed_failure — Sent when Piano is unable to charge the subscriber and the grace period has ended, revoking access.

• subscription_ended / subscription_expired — Sent when the subscription itself expires following the final failed payment attempt.

Upgrades During Grace

For upgrade scenarios that involve a grace period, see the dedicated events under the subscription_created, subscription_ended, term_change, and access_granted / access_revoked webhook types, which include term_change_grace_period_started and term_change_grace_period_ended events.

Special Case: Subscription Upgrades and Term Changes

If a subscriber attempts an upgrade or term change and the payment fails, the destination term's grace period is applied.

If the Destination Term Has a Grace Period

The system may:

• Create and activate the new subscription term in a grace state (even before payment succeeds).

• Mark the prior subscription as upgraded.

• Allow temporary access to the upgraded entitlements during the grace period.

If the Destination Term Has No Grace Period

• The upgrade may fail immediately and the subscriber may receive a term change failure outcome.

Associated email notifications for term changes may include:

• Term Change Grace Period (when grace applies)

• Term Change Failure (when grace does not apply)

Note that if a subscriber is scheduled for an upgrade while already in a grace period due to a failed standard renewal, the system may process the upgrade even if the renewal payment initially failed. This can result in access to upgraded entitlements before payment is successfully collected. If this is not desired for your business rules, monitor subscribers in grace and review how upgrades are scheduled relative to renewal and grace-period behavior.

Common Causes of Renewal Failure

Renewal failures typically result from one of the following:

• Payment method removed

• Card expired

• Card canceled

• Card blocked or does not support the purchase type (processor declines)

To investigate a specific failure:

1. Review transaction history to confirm retries and capture decline or error messages (e.g., "card does not support this type of purchase").

2. If the subscriber has multiple payment methods available, switch the subscription's payment method in the user profile or subscription view in the Dashboard.

3. If declines persist, consult your payment processor (e.g., Stripe) for the detailed decline reason.

4. Always obtain the subscriber's permission before changing payment methods.

Troubleshooting Checklist

1. Confirm the term's grace period setting — this is configured per term.

2. Verify auto-renewal status — check whether the subscription is in auto-renew mode and whether it is already in a grace period workflow.

3. Understand the extended expiration date — remember that the access/expiration date may appear extended during grace by design.

4. Check payment method updates — if the subscriber updated their card, confirm they are waiting for the next scheduled retry, not an immediate charge.

5. Inspect the DOM/CSS for fixed-width containers — if behavior looks wrong in the Dashboard, check for display or rendering issues before assuming a billing error.

6. Review Email Manager templates for:

   • Subscription renewal failure messaging

   • Term change grace period messaging (if upgrades are involved)

7. Monitor failure_counter in event payloads to track retry attempts and identify the final failure.

8. Contact Piano Support if behavior persists beyond the grace period (e.g., charges continuing or access not being revoked as expected).

Last updated: June 26, 2026