Refunding Invoices Externally & Retrying Dunning-Completed Invoices via API

This article explains two common API workflows used by merchants:

• How to mark a Recurly invoice as externally refunded when a refund is issued outside of Recurly (for example, via cash, check, or bank transfer), without moving any funds.
• How to retry a dunning-completed invoice using an alternate payment gateway after the dunning cycle has finished.

Both workflows are supported using the Recurly API v2021-02-25 and are commonly used to ensure accounting accuracy and recover failed payments.

1. Marking an Invoice as Externally Refunded (Without Moving Any Funds)

If a refund is issued outside of Recurly—such as via cash, check, or offline bank transfer— you can still reflect that refund in Recurly for reporting and accounting purposes.

API Request

POST /invoices/{invoice_id}/refund
{
  "refund_method": "all_credit",
  "amount": 100.00,
  "external_refund": {
    "payment_method": "check",
    "description": "Refund issued offline"
  }
}
    

This action results in:

• A refund credit invoice for accurate financial records
• No gateway transaction or movement of funds
• A clear audit trail documenting how and why the refund was issued

2. Retrying a Dunning-Completed Invoice on an Alternate Gateway

Once an invoice has completed its dunning cycle, Recurly will no longer retry it automatically. If the customer updates billing information or you want to retry collection manually, you can do so via the API.

Step 1: Assign a Different Gateway

PUT /invoices/{invoice_id}
{
  "gateway_code": "ALTERNATE_GATEWAY"
}
    

Step 2: Trigger Collection

PUT /invoices/{invoice_id}/collect
    

Recurly will attempt to collect payment using:

• The newly assigned gateway_code
• The customer’s existing stored billing information

Examples with curl

Mark an Invoice as Externally Refunded

curl -X POST "https://v3.recurly.com/invoices/{invoice_id}/refund" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.recurly.v2021-02-25" \
  -d '{
        "refund_method": "all_credit",
        "amount": 100.00,
        "external_refund": {
          "payment_method": "check",
          "description": "Refund issued offline"
        }
      }'
    

Retry a Dunning-Completed Invoice Using Another Gateway

# Assign alternate gateway
curl -X PUT "https://v3.recurly.com/invoices/{invoice_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.recurly.v2021-02-25" \
  -d '{ "gateway_code": "ALTERNATE_GATEWAY" }'

# Trigger collection
curl -X PUT "https://v3.recurly.com/invoices/{invoice_id}/collect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.recurly.v2021-02-25"
    

Best Practices

• Use external refunds only when funds truly moved outside of Recurly.
• Verify the invoice is in a past_due or failed state before retrying collection.
• Confirm the alternate gateway is fully configured and supports the customer’s payment method.

Resources

• API – Refund Invoice
• API – Update Invoice
• API – Collect Invoice