Overview: Recurly Recover
Use Recurly Recover's standalone retry engine to collect on past-due invoices from your existing billing platform — without adopting Recurly for subscription management.
Prerequisites
- An active Recurly account with an API key generated.
- One or more payment gateways configured in Recurly.
- At least one retry window (dunning campaign) configured in the Recurly Admin UI.
Limitations
- Recurly Recover is designed for merchants who don't use Recurly for subscription management — it's not intended to work alongside Recurly Subscriptions.
- Accounts can only be created via the API, not through the Admin UI.
- Each successful API call creates one account with one invoice. Calling the API again with the same account code returns an error.
Definition
Key benefits
Key details
How Recurly Recover works
- A payment fails on your billing platform.
- You pause your internal retry logic for that invoice.
- You call the Recovery API with account details, payment method tokens, prior attempt history, and the retry window you want Recurly to use.
- Recurly creates an account, a past-due invoice, and a failed transaction.
- Recurly calculates the first retry date based on your submission and begins retrying per the assigned retry window.
- When a retry succeeds or the retry window is exhausted, Recurly fires a webhook. You update the invoice state in your system.
Setup
Step 1: Connect your payment gateway
Note the gateway code
Each gateway connection is assigned a unique gateway code. You'll pass this value in API requests to route transactions to the correct gateway. If you need to route different card types or merchant category codes through separate accounts, you can add multiple connections for the same provider — each gets its own gateway code.
Step 2: Configure a retry window
A retry window defines how many days Recurly will attempt to collect on a past-due invoice. Retry windows are configured using Recurly's dunning campaign feature.
dunning_campaign_id, you can easily run A/B tests by assigning different campaign codes at submission time.Step 3: Generate your API key
Step 4: Configure webhooks
Recurly fires webhook events at key points in the retry lifecycle. Configure at least one webhook endpoint so your system can respond when a payment is recovered or a retry window closes.
| Event | Fires when |
|---|---|
successful_payment | A retry attempt successfully collects payment |
failed_payment | A retry attempt fails |
new_dunning_event | A dunning step fires per the retry window configuration |
closed_invoice | An invoice is marked as paid or failed |
uuid field in payment webhook events is a transaction ID, not an invoice ID. Use GET /transactions/uuid-{uuid} to retrieve the transaction, then follow the invoice relationship if you need invoice details. Do not query /invoices/{uuid} with a transaction ID.For full webhook event details, see the Webhooks documentation.
Step 5: Submit a failed invoice
Call POST /invoices/recovery to submit a failed invoice for collection. A successful request creates a Recurly account, a past-due invoice, and an initial failed transaction — and immediately begins the retry schedule.
Endpoint
POST https://v3.recurly.com/invoices/recoveryRequest
{
"currency": "str",
"due_at": "2019-08-24T14:15:22Z",
"po_number": "string",
"external_recovery_eligible": true,
"account": {
"address": {
"phone": "string",
"street1": "string",
"street2": "string",
"city": "string",
"region": "string",
"postal_code": "string",
"country": "string"
},
"billing_infos": [
{
"first_name": "string",
"last_name": "string",
"company": "string",
"address": {
"phone": "string",
"street1": "string",
"street2": "string",
"city": "string",
"region": "string",
"postal_code": "string",
"country": "string"
},
"ip_address": "string",
"gateway_code": "string",
"primary_payment_method": true,
"backup_payment_method": true,
"payment_gateway_references": [
{
"token": "string",
"reference_type": "stripe_confirmation_token"
}
],
"network_transaction_id": "string",
"transactions": [
{
"gateway_error_code": "string",
"merchant_advice_code": "st",
"attempted_collection_date": "2019-08-24T14:15:22Z"
}
]
}
],
"code": "string",
"email": "[email protected]",
"custom_fields": [
{
"name": "string",
"value": "string"
}
],
"dunning_campaign_id": "string"
},
"line_items": [
{
"tax": 0,
"custom_fields": [
{
"name": "string",
"value": "string"
}
],
"harmonized_system_code": "string",
"product_code": "string",
"quantity": 1,
"description": "string",
"unit_amount": 0
}
]
}Step 6: Handle the response
A successful 201 response confirms that Recurly has created the account and started the retry process. Save the invoice_id from the response — you'll need it to stop retries later.
The attempt_next_collection_at field in the response shows when Recurly will make its first retry attempt.
Response
{
"object": "string",
"charge_invoice": {
"id": "string",
"uuid": "string",
"object": "string",
"type": "charge",
"origin": "carryforward_credit",
"state": "open",
"account": {
"id": "string",
"object": "string",
"code": "string",
"email": "[email protected]",
"first_name": "string",
"last_name": "string",
"company": "string",
"parent_account_id": "string",
"bill_to": "parent",
"dunning_campaign_id": "string"
},
"billing_info_id": "string",
"subscription_ids": ["string"],
"previous_invoice_id": "string",
"number": "string",
"collection_method": "automatic",
"po_number": "string",
"net_terms": 0,
"net_terms_type": "net",
"currency": "str",
"discount": 0,
"subtotal": 0,
"subtotal_after_discount": 0,
"tax": 0,
"total": 0,
"refundable_amount": 0,
"paid": 0,
"balance": 0,
"dunning_campaign_id": "string",
"due_at": "2019-08-24T14:15:22Z",
"closed_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}Stopping retries
You can stop all future retry attempts on an invoice at any time while it's in a past_due state.
Mark as paid — use when payment was collected outside of Recurly:
PUT https://v3.recurly.com/invoices/{invoice_id}/mark_successfulMark as failed — use when you want to abandon collection:
PUT https://v3.recurly.com/invoices/{invoice_id}/mark_failedUse the invoice_id returned in the original API response. Once marked, Recurly won't make any further retry attempts on that invoice.
Payment method wallet
When the Wallet feature is enabled, you can designate payment methods as primary or backup in your API request. You can submit multiple payment methods, but only one can be marked as primary.
FAQs
Do I need Recurly Subscriptions to use Recurly Recover?
No. Recurly Recover is designed as a standalone retry engine for merchants using other billing platforms. Combining Recurly Recover with Recurly Subscriptions is not recommended.
What happens when I submit a past-due invoice via the API?
Recurly creates an account (without a subscription), a charge invoice, and one or more failed transactions. Billing information is stored and Recurly automatically calculates the next collection attempt date based on your submission.
Can I stop retries on a past-due invoice?
Yes. While an invoice is in a past-due state, you can cancel all future collection attempts by marking the invoice as failed or paid using the Recurly Invoice API.
What happens when the retry window closes without a successful payment?
The invoice is marked as failed and a webhook event fires. No further retries are made. You can then handle the outcome in your system — for example, suspending access or triggering a win-back campaign.
What if a customer provides a new payment method outside of Recurly?
Mark the in-flight Recurly invoice as successful (if payment was collected) or as failed (to stop the current attempt), then submit a new recovery request with the updated payment method token.
Can I use Recurly Recover with existing Recurly Subscriptions customers?
Recurly Recover is not intended to work alongside Recurly Subscriptions — payment recovery is already included in your Recurly Subscriptions plan. For questions about which solution fits your needs, contact Recurly Sales or email [email protected].