Smart Retries

Yuno’s Smart Retries help recover declined recurring credit card payments by retrying them on an optimized schedule. By retrying at the right moments, Smart Retries increase the likelihood of payment success, ensuring a consistent revenue stream and reducing involuntary subscriber churn.

Key advantages

Yuno’s Smart Retries offer several benefits that enhance payment processes and revenue recovery:

Data-driven decision-making: Uses a proven retry schedule, or machine-learning-based retry timing via the SMART strategy.
Enhanced revenue retrieval: Increases the chances of successfully collecting payments.
Decreased subscriber turnover: Minimizes disruptions and involuntary subscriber departures.
Flexible logic: Allows customization of retry schedules to maximize success opportunities.
Comprehensive approach: Works in conjunction with other revenue recovery strategies.

Retry schedule

By default, Yuno applies the fixed retry schedule below. Each delay is measured from the previous attempt, not cumulatively from the first attempt. You can also switch to machine-learning-based retry timing, which adapts the moment of each retry per transaction, by setting strategy to SMART — see Machine-learning retry timing.

Attempt	Delay after the previous attempt	Total time after the first attempt
First try (initial charge)	-	-
Retry 1	5 hours	~5 hours
Retry 2	12 hours	~17 hours
Retry 3	24 hours	~41 hours
Retry 4	36 hours	~77 hours (~3.2 days)
Retry 5	48 hours	~125 hours (~5.2 days)
Retry 6	96 hours	~221 hours (~9.2 days)

The last retry is attempted roughly 9.2 days after the initial failed charge.

Customization

Every business model is unique, so we allow merchants to define specific rules to enhance the flexibility of our retry schedule. When creating the subscription object, you can use the retries structure to make adjustments:

Parameter	Type	Description	Example
`retry_on_decline`	bool	Indicates whether to retry a payment after a first decline. Defaults to false. This flag is the only switch that enables retries; there is no dashboard toggle.	TRUE
`amount`	number	Number of retries the subscription will attempt. The maximum equals your environment’s configured retry schedule length — 6 in production. A value above the cap is rejected with `400` (`Max retries attempts exceeded`). This cap is set per environment and is not configurable per account via the API.	4
`strategy`	string	The retry strategy. Allowed values: DEFAULT, SMART and CUSTOM_SCHEDULE. DEFAULT uses the fixed schedule above. SMART uses machine-learning-based retry timing — see Machine-learning retry timing. CUSTOM_SCHEDULE uses the per-attempt schedule you provide.	`CUSTOM_SCHEDULE`
`stop_on_hard_decline`	bool	When true and a hard decline is detected, retries stop for the current cycle only. On its own, the subscription stays ACTIVE, billing advances to the next cycle, and no cancel/pause or subscription webhook is emitted. If `cancel_on_exhausted_retries` is also true, the subscription is canceled instead — see Canceling a subscription when retries run out.	TRUE
`cancel_on_exhausted_retries`	bool	When true, the subscription is canceled once retries for a billing cycle end without a successful payment, instead of rolling forward to the next cycle. Defaults to false. Can be set at creation or changed later with Update Subscription. See Canceling a subscription when retries run out.	TRUE
`schedule`	object	Contains attempt and delay_seconds fields	Attempt: 2, `delay_seconds`: 86400

The maximum number of retries equals your environment’s configured retry schedule length: 6 in production. Sandbox is currently limited to 5 and is being aligned to match production.

strategy: DEFAULT applies the fixed schedule above. Use SMART for machine-learning-based retry timing, or CUSTOM_SCHEDULE together with the schedule array to define your own delays.

Machine-learning retry timing

Set strategy to SMART to have Yuno’s machine-learning model choose when each retry is attempted, instead of using the fixed schedule. The model weighs signals such as the decline reason, the country, the card issuer and the payment provider to pick the moment most likely to succeed.

{
  "retries": {
    "retry_on_decline": true,
    "amount": 4,
    "strategy": "SMART"
  }
}

SMART changes retry timing only. It does not change how many retries you get: amount still controls that, and the same per-environment maximum applies. Any schedule array sent alongside strategy: SMART is ignored.

Machine-learning timing is applied from the second retry onward. The first retry always uses the standard delay from the fixed schedule above.

If a timing decision is not available in time, the retry falls back to the fixed schedule above. Retries are never skipped or dropped because of this — only their timing changes.

SMART is available to all accounts.

Canceling a subscription when retries run out

By default, when every retry for a billing cycle has been attempted and none succeeded, the subscription stays ACTIVE and billing rolls forward to the next cycle. A subscription backed by a permanently dead card therefore keeps generating failed charges indefinitely. Set cancel_on_exhausted_retries to true — at creation or via Update Subscription — to change that:

{
  "retries": {
    "retry_on_decline": true,
    "amount": 3,
    "cancel_on_exhausted_retries": true
  }
}

When retries for a cycle end without a successful payment, Yuno then:

Sets the subscription status to CANCELED.
Sets cancellation_source to RETRIES_EXHAUSTED.
Stops all future scheduled billing for the subscription.
Sends one SUBSCRIPTION.CANCEL webhook.

This applies whichever way the retries ended — the schedule running to its last attempt, or stop_on_hard_decline ending the cycle early after a hard decline. In both cases cancellation_source is RETRIES_EXHAUSTED.

cancel_on_exhausted_retries defaults to false. If you omit it, subscriptions behave exactly as they do today. No existing subscription changes behavior.

This cancellation is final. A canceled subscription is no longer billable, so Retry Subscription is rejected for it. Without this flag you can manually rescue a subscription whose retries were exhausted; with it enabled, that option is gone once the cancellation happens. Enable it only if an exhausted retry schedule should genuinely end the customer’s subscription.

cancel_on_exhausted_retries can be set at creation or changed afterward with Update Subscription.

This flag applies to renewal cycles. Subscriptions created with initial_payment_validation: true already cancel themselves when their first payment fails, and that path reports cancellation_source as SYSTEM rather than RETRIES_EXHAUSTED.

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Key advantages

Retry schedule

Customization

Machine-learning retry timing

Canceling a subscription when retries run out

​Key advantages

​Retry schedule

​Customization

​Machine-learning retry timing

​Canceling a subscription when retries run out

Key advantages

Retry schedule

Customization

Machine-learning retry timing

Canceling a subscription when retries run out