Understanding Refundable Balances on Invoices (and Why Some Refunds Can’t Be Combined)

In Recurly, the amount you can refund to the original payment method is governed by a per-invoice value commonly referred to as the refundable balance. This becomes especially important when credits were issued or redeemed against an invoice, or when proration creates a mix of charges and credits.

What is “Refundable Balance”?

Refundable balance is the remaining amount on a specific invoice that can be refunded back to the original payment method through Recurly.

• It is tracked per invoice (not as one global “refund pool” across the account).
• At invoice creation, it typically starts at the invoice total.
• Refunds and certain credit actions reduce it.

How Refundable Balance Is Consumed

When you initiate actions that return money (or effectively re-allocate money) from an invoice, Recurly uses the refundable balance on that invoice.

Why You Sometimes Can’t Combine Two Refunds into One

Merchants often ask: “Can I combine two refunds into one refund so my customer only sees one credit back to their card?” In many cases, not within Recurly—because Recurly must respect the refundable balance remaining on the invoice you are refunding from.

• A single refund in Recurly is typically anchored to a specific invoice.
• If the invoice you want to refund from does not have enough refundable balance remaining, Recurly cannot refund the full desired amount from that invoice.
• If your desired total spans refundable balances across multiple invoices, this often results in multiple refunds.

What to Do When the Desired Refund Exceeds the Refundable Balance

If the invoice(s) involved no longer have enough refundable balance to support the desired one-time refund amount, there are a few practical options:

Option 1: Refund across multiple invoices (multiple refunds)

1. Refund what remains refundable on the first invoice.
2. Refund the remaining amount from another invoice (if available) with sufficient refundable balance.

Option 2: Refund from a different invoice with sufficient refundable balance

If there is another invoice (often an older invoice) that still has enough refundable balance remaining, you may be able to issue the refund from that invoice instead.

Option 3: Refund directly in the gateway (outside Recurly)

If Recurly’s available invoices do not have sufficient refundable balances remaining, the remaining amount may need to be refunded directly through the payment gateway, depending on the merchant’s process and reconciliation needs.

Example Scenario (Proration / Redeemed Credit)

A common way this occurs is when a subscription is changed “now” with default proration behavior, creating a prorated credit that is immediately applied/redeemed, leaving insufficient refundable balance on the original invoice to process a single refund for the “intended difference.”

Best Practices to Avoid This Scenario

• Be explicit with proration settings when performing immediate subscription changes via API to avoid unintended prorated credits/charges.
• If merchants frequently forget to include proration settings, consider adjusting the site-level default proration behavior so the default outcome matches their intended policy.
• When a mistaken proration is identified quickly, evaluate whether refunding the most recent charge invoice directly (before additional credit redemption occurs) is more likely to preserve refund flexibility.