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. You can set the retries structure when creating the subscription, and change it later on an existing subscription with Update Subscription — every field except cancel_on_exhausted_retries, which is create-only:

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. Create-only: it cannot be changed later — Update Subscription rejects a different value with `400`. See Canceling a subscription when retries run out.	TRUE
`schedule`	object	Per-attempt schedule for `CUSTOM_SCHEDULE`, an array of objects with `attempt` and `delay_seconds` fields. Up to 7 attempts; attempt numbers must run sequentially from 1, and each `delay_seconds` must be between 1 and 604800 (7 days). Sending it without `strategy` implies `CUSTOM_SCHEDULE`, and the retry amount follows the schedule length.	Attempt: 2, `delay_seconds`: 86400

Updating retries on an existing subscriptionUpdate Subscription accepts the same retries object (a sent schedule replaces the stored one as a whole). The change applies the next time retries are scheduled: a billing cycle already running its retries finishes on the configuration it started with, and the new configuration takes effect from the next cycle.

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.

Subscriptions awaiting recovery

Where the PAST_DUE status is enabled for the account, a failed recurring charge moves the subscription from ACTIVE — or from TRIALING — to PAST_DUE and emits a subscription.past_due webhook. The subscription keeps billing and can still be canceled while it is there; the next successful charge returns it to the status it came from and emits the matching subscription.active or subscription.trialing event. Where the status is not enabled, a failed charge leaves the subscription in ACTIVE while the retries run, and only the payment.purchase webhook reports the decline. Contact your Yuno representative to have PAST_DUE enabled.

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 in its current status 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 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 only be set at creation. Update Subscription rejects a value different from the stored one with 400 (The field 'retries.cancel_on_exhausted_retries' can only be set when the subscription is created); the rest of the retries object stays updatable.

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

Subscriptions awaiting recovery

Canceling a subscription when retries run out

​Key advantages

​Retry schedule

​Customization

​Machine-learning retry timing

​Subscriptions awaiting recovery

​Canceling a subscription when retries run out

Key advantages

Retry schedule

Customization

Machine-learning retry timing

Subscriptions awaiting recovery

Canceling a subscription when retries run out