Failed payments and dunning

Recover failed subscription payments with reminder emails and a grace period before access ends. This needs TierMint Pro.

What happens when a renewal payment fails

Dunning starts on its own when a subscription payment fails, for example on an expired card or a bank decline. There is nothing to switch on. It applies to subscriptions only, never to one-time purchases.

When a payment fails, TierMint:

1. Moves the subscription to Past due.
2. Schedules three reminder emails to the customer. See Reminder emails.
3. Keeps the license working past its end date for a grace period of 14 days. See The grace period.
4. Gives up when the grace period ends without a payment. See What happens when the grace period ends.

The payment gateway retries the charge on its own schedule. TierMint does not retry charges. For Stripe, the retry schedule is set in your Stripe Dashboard: Stripe's Smart Retries guide explains it. Set the retry window and the final action so that Stripe keeps retrying for at least 17 days after the failure. With TierMint's defaults, that is the 3 extra days on the license plus the 14-day grace. If Stripe cancels the subscription first, access ends when Stripe gives up.

As soon as a retried payment succeeds, the subscription returns to Active, the remaining reminders stop and the license is extended to the new paid period.

Reminder emails

TierMint sends the same reminder at three points after the payment fails:

Reminder	When it is sent
1	When the payment fails.
2	3 days later.
3	7 days after the failure. This last reminder warns that the subscription will be cancelled and access will end.

The subject reads "Action needed: your payment to (store name) could not be processed". The email has an Update payment method button. It goes to the email address on the subscription's first order.

Before each reminder goes out, TierMint checks the subscription again. If it is no longer past due, the reminder is not sent.

The button links to your site's home page unless you change it. Point it at the page with your subscription manager: see Send customers to your subscription page.

What the customer sees

A past-due subscription shows a Past due badge in the subscription manager, with the alert "Your last payment could not be processed. Please update your payment method to keep your subscription active." The customer clicks Update payment method to change the card in Stripe's customer portal. The subscriptions page explains the subscription manager.

The customer's software keeps validating and updating through the reminders and the grace period, unless the gateway ends the subscription first. The customer's account page is stricter: it shows the license as expired from its stored end date and shows no Download update link for it, even while the software still works.

The grace period

A subscription license has a stored end date: the last paid period plus 3 days. While the subscription is past due, TierMint treats the license as valid for 14 more days after that date. The stored date itself does not change, so TierMint → Licenses still shows it.

For example, a monthly subscription paid through 1 March has a license end date of 4 March. If the next payment fails, the license keeps working until 18 March.

A license with no end date, such as a Lifetime license, keeps working through dunning and after it. The subscription itself is still cancelled 14 days after the failure.

What happens when the grace period ends

If no payment arrives by the end of the grace period, TierMint:

1. Marks the subscription Cancelled.
2. Expires the license.
3. Emails the customer that the subscription has ended, with a Resubscribe button.

TierMint marks the subscription cancelled in your store only. It does not send a cancellation to Stripe or PayPal. Check what your gateway does after its last retry, so that it stops billing too. For Stripe, this is in the same subscription settings as the retry schedule.

A cancelled subscription is final. The customer buys a new subscription to get access back. If the gateway still collects a late retry, TierMint records the payment and restores the license, while the subscription stays cancelled. Make sure the gateway stops billing.

Send customers to your subscription page

Two filters set where the email buttons point. Both default to your site's home page.

Filter	Button
tiermint_dunning_manage_url	Update payment method in the reminder emails.
tiermint_dunning_resubscribe_url	Resubscribe in the email sent when a subscription ends.

Each filter receives the URL and the subscription. This snippet points the reminder button at a page with the subscriptions slug:

add_filter( 'tiermint_dunning_manage_url', function ( $url, $subscription ) {
	return home_url( '/subscriptions/' );
}, 10, 2 );

Emails you can and cannot switch off

Dunning uses these emails:

Email	ID	When it is sent
Payment failed reminder	payment_failed_dunning	At each reminder step.
Subscription ended	subscription_cancelled	Each time a subscription becomes Cancelled: when dunning gives up, and when a customer or you cancel. It is not sent when a subscription becomes Expired.

Neither email has a switch in wp-admin. The Emails tab under TierMint → Settings has four fields: From name, From address, Send purchase receipts and Send license delivery emails. The sender name and address apply to the dunning emails too. The two toggles do not.

Both emails are sent unless the stored TierMint settings turn them off. TierMint reads the keys emails.enabled_payment_failed_dunning and emails.enabled_subscription_cancelled in the tiermint_settings option, and treats a missing key as on. A developer can set a key to false to stop that email. Turning off subscription_cancelled stops it for every cancellation, not only for dunning.

You can change the wording with a theme override. Copy the template into your theme folder at these paths:

Email	Theme path
Payment failed reminder	tiermint/emails/payment-failed-dunning.php
Subscription ended	tiermint/emails/subscription-cancelled.php

Change the schedule and the grace period

Two more filters change the timing. Each receives the default value and the subscription.

Filter	Default	What it changes
tiermint_dunning_schedule_days	[0, 3, 7]	The days after the failure on which reminders are sent. TierMint sorts the list and drops duplicates. The last entry gets the final-reminder wording.
tiermint_dunning_grace_days	14	The days the license keeps working past its end date. The minimum is 1.

Common questions

A customer says their software stopped right after a failed payment. Why?

It should not stop during the grace period. The license keeps working until its end date plus the grace days. Check the license end date under TierMint → Licenses, then add 14 days, or the value your site sets with tiermint_dunning_grace_days.

Do I need to set anything in Stripe for dunning?

Not for TierMint's reminders and grace period. Stripe's retry schedule, and what Stripe does after its last retry, are set in your Stripe Dashboard.

Can I send more reminders, or send them at other times?

Yes, with the tiermint_dunning_schedule_days filter. It takes a list of day offsets from the failure.

Where does the Update payment method button go if I have not set the filter?

To your site's home page. Set tiermint_dunning_manage_url to the page with your subscription manager.