Overview
Smart Retries is Yuno’s automatic retry mechanism for failed subscription payments. When a recurring payment fails (due to insufficient funds, expired card, or temporary processor issues), Smart Retries attempts to collect the payment again based on a configurable schedule. Combined with dunning management, this feature helps recover revenue and reduce involuntary churn.
How Smart Retries Work
- A scheduled subscription payment fails.
- The subscription enters
PAST_DUE status.
- Smart Retries schedules retry attempts according to your configuration.
- Between retries, optional dunning emails notify the customer.
- If a retry succeeds, the subscription returns to
ACTIVE.
- If all retries are exhausted, the subscription is cancelled (or a custom action is triggered).
Smart Retries use intelligent timing to maximize recovery rates. Yuno analyzes historical payment patterns to determine optimal retry windows, such as retrying near typical payday dates.
Configuring Retry Schedules
Define your retry schedule when creating or updating a subscription configuration.
curl --request POST \
--url https://api.y.uno/v1/subscription-configs \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
"retry_schedule": {
"max_retries": 4,
"intervals": [1, 3, 5, 7],
"interval_unit": "DAYS"
},
"dunning": {
"enabled": true,
"notify_customer": true,
"final_action": "CANCEL"
}
}'
Retry Schedule Options
| Parameter | Type | Description |
|---|
max_retries | Integer | Maximum number of retry attempts (1-10) |
intervals | Array | Days between each retry attempt |
interval_unit | String | Unit for intervals: HOURS or DAYS |
Example Schedules
| Strategy | Intervals (days) | Total Window | Best For |
|---|
| Aggressive | [1, 1, 2, 3] | 7 days | Low-cost subscriptions |
| Standard | [1, 3, 5, 7] | 16 days | General purpose |
| Conservative | [3, 5, 7, 14] | 29 days | High-value subscriptions |
Dunning Management
Dunning is the process of communicating with customers about failed payments. Yuno can automatically send notifications at each retry stage.
Dunning Configuration
| Parameter | Type | Description |
|---|
enabled | Boolean | Enable/disable dunning notifications |
notify_customer | Boolean | Send email notifications to the customer |
final_action | String | Action after all retries exhausted: CANCEL, PAUSE, or NONE |
If final_action is set to CANCEL, the subscription will be permanently cancelled after all retries are exhausted. Use PAUSE if you want to allow manual recovery.
Decline Categories and Retry Logic
Not all payment failures should be retried. Yuno categorizes declines to optimize retry behavior:
| Decline Type | Description | Retry? | Example |
|---|
| Soft decline | Temporary issue, likely to resolve | Yes | Insufficient funds, timeout |
| Hard decline | Permanent issue, will not resolve | No | Stolen card, closed account |
| Processor error | Infrastructure issue | Yes | Gateway timeout, network error |
Hard declines (stolen card, invalid account) are not retried regardless of your retry schedule. This prevents unnecessary processing and potential fraud flags.
Webhook Events for Retries
| Event | Description |
|---|
subscription.payment.retry_scheduled | A retry has been scheduled |
subscription.payment.retry_success | A retry payment succeeded |
subscription.payment.retry_failed | A retry payment failed |
subscription.dunning.final_action | All retries exhausted, final action taken |
Best Practices
- Start with the Standard schedule (1, 3, 5, 7 days) and optimize based on recovery data.
- Enable dunning notifications to give customers a chance to update their payment method.
- Use
PAUSE instead of CANCEL for high-value subscriptions to allow manual recovery.
- Monitor retry metrics in the Yuno Dashboard to identify patterns and adjust schedules.
- Implement
subscription.payment.retry_failed webhooks to trigger in-app notifications or support outreach.
You can view retry history and recovery rates in the Yuno Dashboard under Subscriptions > Analytics > Recovery.
