Use refunds to return money to a customer from a transaction or invoice. You can refund the entire amount, a specific amount, or selected line items — with options to prorate subscription charges and control how credits are applied.

Available on all Recurly plans

1Definition 2Key benefits 3Key details 4Refund from the Admin UI 5Refund via API 6Troubleshooting

Prerequisites

Staff access to Invoices and Transactions in the Recurly Admin UI, or API credentials with scope to refund invoices

Limitations

Refunds are always issued to the original payment method (the same card or bank account used for ACH) and are tied to the original gateway. They cannot be routed to a different payment method or gateway
Unsettled transactions can be voided instead of refunded. Some gateways also allow refunds against unsettled transactions, but this is not recommended
Voided and uncaptured authorization transactions cannot be refunded
Percentage refunds on invoices require the Credit Memos feature flag to be enabled

Definition

A refund reverses all or part of a previously collected charge. In Recurly, refunding an invoice or its underlying transaction creates a refund invoice and a refund transaction, and can optionally return account credit before issuing money back.

Key benefits

Work from one place Refund from the invoice, the transaction, or via API — whichever fits your workflow.

Fine-grained control Refund by full amount, a specific dollar or percentage amount, or selected line items — exactly what you need and nothing more.

Accurate billing math The refund preview respects proration, taxes, discounts, and quantities so you know exactly what will be returned before confirming.

Consistent accounting Recurly generates refund invoices and refund transactions for every reversal, keeping your audit trail clean.

Key details

Refund types

Type	What it does	Typical use
Full	Returns the entire original charge.	Billing error or immediate cancellation.
Amount	Returns an exact currency amount.	Goodwill credit or partial service issue.
Line items	Returns selected lines with optional proration and quantities.	Plan swaps, partial periods, or item-level adjustments.

Credit handling

When an invoice contains credit line items and you're issuing a partial refund, you can control the order in which value is returned.

Option	Result
Credit first (default)	Refund returns account credit first, then creates a transaction for any remaining amount.
Transaction first	Refund issues money back to the customer first; any remainder is returned as account credit.

Taxes, discounts, and proration

The refund preview calculates the exact impact of your selection before you confirm:

Line-item refunds respect original taxability and discount allocation
Proration applies to subscription charges when selected on the refund screen
The preview shows all calculated taxes, discounts, and proration adjustments

What gets created

When a refund is completed, Recurly generates two records:

A refund invoice reflecting the reversal, including taxes and discount allocation
A refund transaction against the original payment method

Refund from the Admin UI

Open the transaction or invoice

Go to the customer's account and select the transaction in Transactions, or the invoice in Invoices.

Initiate the refund

On the Transaction details page, select Refund transaction. On the Invoice details page, select Refund invoice.

Choose what to refund

Select the refund scope using one of the options below.

Line items — Select specific charge lines. Optionally prorate subscription charges or select specific quantities.
Specific amount — Select "Refund a partial item or specific amount?" and enter a custom amount. The amount cannot exceed the original transaction value.
Unsettled transactions — Only a full refund (void) is available until the gateway settles the charge.

Set the credit return order (partial refunds only)

If the invoice includes credit line items and you're issuing a partial refund, choose how to apply value using the radio buttons at the top of the page.

Credit first is the defaultRecurly returns credit to the account before issuing money back. Select Transaction first to reverse this order.

Preview the refund

Select Preview refund to review discounts, taxes, credits, and totals before committing.

Complete the refund

Select Refund charges to finalize. Recurly creates a refund invoice and a refund transaction.

Refund via API

To refund an invoice programmatically, use the Refund Invoice endpoint in Recurly's API.

API referenceSee Refund an Invoice in the Recurly API documentation for the full endpoint spec, required fields, and request examples.

Troubleshooting

Why can't I refund — the transaction shows as unsettled?

Unsettled transactions can only be fully reversed with a void. A refund is not available until the gateway settles the charge, which typically happens at end of day. Wait for settlement, then issue the refund — or proceed with a void if you want an immediate full reversal.

The gateway or bank blocked my refund attempt. What should I do?

You may be outside the gateway's refund window (often 30–60 days after the original transaction), or the original payment method may no longer be able to receive the refund. In these cases, consider issuing an offline credit outside the processor and recording the adjustment in Recurly manually.

I'm getting a validation error via the API. How do I fix it?

Confirm that the type field and all required parameters are present in your request. For line-item refunds, verify that the line IDs and quantities are valid for the original invoice. Refer to the Refund an Invoice API reference for the full parameter spec.