The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Retry Logic

When a recurring credit card payment fails, our Revenue Optimization Engine uses machine learning to schedule a transaction retry attempt at a time when it is more likely to succeed.

Recurly Retry Logic

Recurly has the advantage of working with thousands of subscription businesses from a wide range of industries. This gives us access to hundreds of millions of data points that encompass billions of attributes from many different types of companies. We draw upon this data and our years of subscription experience to intelligently retry declined transactions. By doing this, Recurly helps you increase overall revenue from payment success, reduces customer interruptions in access to your product or service and decreases involuntary subscriber churn.

Revenue Optimization Engine

Every declined transaction is different, which makes a static, one-size-fits-all retry schedule less effective. For customers on Recurly Professional, Elite and Enterprise plans, we use machine learning to craft a more intelligent retry schedule that is specifically tailored to each individual declined transaction.

This means that our logic does not stay static and is not based upon decline error type only. Our platform analyzes each invoice that received a decline transaction and uses historical data from similar invoices/declines to determine the date and time of the next transaction retry on that invoice. We will continually add more granular inputs to the platform to help increase accuracy and likelihood of transaction success.

If you are on our Core plan and interested in moving onto this platform to increase revenue recovery, please reach out to Recurly support to learn more about the benefits of upgrading.

General Guidelines

Soft Declines

Soft declines such as insufficient funds, a generic error, or a temporary hold will be retried by Recurly. Recurly will attempt to use the same payment method. After an invoice fails its first collection attempt and before the Dunning period of that invoice expires, Recurly automatically attempts to collect the invoice using strategies optimized for the type of failure, the nature of the transaction, and characteristics of the customer. In order to optimize the efficiency of our retry schedule, we alter the retry schedule consistently to find the best fit for your business.

Hard Declines

Hard declines, such as customer closing their account, cannot be resolved immediately; and subsequent attempts with the same payment method will not succeed. Recurly does not retry transactions with a hard decline.
Exception A: If Account Updater or the customer update billing information (number updated or expiration date updated), then an immediate one-time retry will be initiated.

Gateway Payment Issues

Try Again/Gateway Error
Every 2 days*

Issuer or Gateway Unavailable
Every 3 days*

Communication/Configuration Error
First retry up to 2 times, 4 hours apart
Next retry up to 6 times, 1 day apart
Finally retry through end of dunning cycle, 3 days* apart

Maximum Retries

The transaction retry attempts on an invoice will stop after 7 transaction declines from the payment gateway, 20 total transaction attempts (including gateway unavailability), or 60 total days since the invoice creation date.

Other Guidelines

Initial transactions (at sign up) and one-time transactions do not use the same retry logic

Manual Retry/Force Collection

A forced collection attempt can occur at any time by clicking the Attempt Collection Now button on the Invoice Details page of a past due invoice. If the past due invoice is still in the automated retry process, each forced collection will increment the total number of transactions allowed for the automated retry schedule. This means you may reach your max transaction count for automated retries early if you click the button a lot.

Once the invoice reaches the maximum number of retry attempts, you will see "Retry schedule complete" displayed in the "Next Attempt:" section. You can continue to force collection, but at this point Recurly is not automatically retrying collection for you. It is important to note that the dunning schedule will end the automated retry schedule, even if the max number of transactions have not been completed.

Other Revenue Recovery Strategies

Retries work alongside the Dunning customer communication process. As a Recurly merchant, you can control the communications that your customers receive while the Dunning period is ongoing (if the invoice is collected because the customer has updated their payment information or a retry has been successful, the Dunning period will cease). For more information on the Dunning customer communication process, please see the Dunning Management page.

Retry Logic


When a recurring credit card payment fails, our Revenue Optimization Engine uses machine learning to schedule a transaction retry attempt at a time when it is more likely to succeed.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.