Key benefits

Key details

Credit invoice types

Credit invoices come in three types, each serving a distinct purpose.

Credit

A credit invoice that isn't linked to any specific charge or invoice — typically a custom or promotional credit. Because it isn't tied to a charge, it doesn't reverse discounts or taxes. When issued, a New Credit Invoice email is sent to the customer.

Refund

A credit invoice that reverses previously issued charges. Generated when a subscription changes immediately with prorated credits, or when an invoice is directly refunded. The email sent depends on the event that triggered the refund.

Refund invoices use the billing and shipping information from the original invoice, even if the current account address has been updated.

Write-off

A credit invoice that offsets charges on a corresponding failed invoice. When Credit Invoices is enabled, every failed invoice is automatically paired with a write-off credit invoice to balance it to zero.

Credit payments

When a credit invoice's balance pays off a charge invoice, a credit payment records the amount that reduced both balances. Credit payments appear on the invoice and can be exported for a detailed audit trail.

Credit payment actions track the application or removal of credit balances — including applying an open credit balance to a charge invoice, recording balance write-offs, removing credit balances, and refunding a credit payment as a cash transaction. These actions are available in the Credit Payments export or via the API.

Invoice origins

The origin attribute on an invoice identifies the event that created it, providing context for reporting and reconciliation. You can view an invoice's origin on the Invoice Details page, filter by it on the Invoices Index page, and access it in exports, the API, and webhooks.

Subscription changes and credit invoices

Immediate subscription changes — both upgrades and downgrades — separate credits from charges. A single subscription change can result in a charge invoice, a credit invoice, or both.

For example, changing from a Silver plan to a Gold plan generates a credit invoice for the remaining Silver balance and a separate charge invoice for the Gold upgrade. Only one Subscription Change email is sent to the customer. If PDF attachments are enabled on your Recurly emails, the customer receives two invoice PDFs — one for each invoice.

Refund capabilities

Refunding an invoice creates a refund credit invoice with credit adjustments. If the original invoice was paid with credit, the refunded amount transfers as part of the credit balance on the new refund credit invoice.

Example: An original invoice of $100 — paid with $20 credit and an $80 credit card transaction — refunded entirely to credit produces a refund credit invoice with a total of ($100), no refund transactions, and a credit balance of ($100).

Advanced refund options

Prorated refund

If you issue a prorated refund, you can later refund the remaining amount on the original invoice. This option is available for refund credit invoices issued after Credit Invoices was enabled. Legacy refund invoices don't support this option.

Refund to credit balance

Instead of refunding to the original payment method, you can refund to the customer's credit balance. This is useful when the customer has future purchases, since the balance will automatically be applied as payment.

Refund credit payment to original payment method

If an invoice was paid with a credit payment that originated from a refundable transaction, the credit payment can be refunded as a transaction — keeping a clean audit trail.

Handling failed refunds

If a refund transaction declines, Recurly creates a refund credit invoice by default and retains the transaction amount as part of the credit balance on the invoice. You can also choose to block all declined refunds, retry the refund transaction, record an external refund transaction, or void the credit invoice — depending on your business needs.

Write-offs

When a charge invoice fails — either directly or at the end of the dunning cycle — a write-off credit invoice is generated automatically. This invoice zeroes out the failed invoice's balance by creating credit adjustments that mirror the original charges, including descriptions, taxes, and discounts. These adjustments carry a credit reason code of write_off, and the credit invoice itself has an origin of write_off for easy identification.

The write-off invoice's balance is immediately applied to the failed invoice via a credit payment labeled write_off, closing the write-off credit invoice on creation.

Voiding credit invoices and balances

If a credit was issued in error, its balance can be voided — maintaining the audit trail while removing the credit.

Full credit invoice voiding: If a credit invoice still has its full original balance (no credit payments or refund transactions have reduced it), the entire invoice can be voided. The invoice moves to a voided state, and the credit balance is removed via a credit payment labeled reduction.

Partial credit balance voiding: If only a portion of the credit invoice's balance remains, the full invoice can't be voided. The remaining balance can still be removed, which creates a credit payment labeled reduction and closes the credit invoice.

To track removed credit balances, use the Credit Payments export filtered by the reduction action.

Credit limitations

Each credit is associated with its originating charge to ensure accurate reversal of discounts and taxes. The total of all credits against a charge can never exceed the original charge amount.

Tax implications

Refund and write-off credit invoices reverse taxes if the original charge invoice collected them. One-off credit invoices don't reverse taxes, since they aren't linked to specific charges.

Avalara AvaTax: Recurly commits every credit invoice to AvaTax on issuance. If a credit balance is voided, the committed document is also voided in AvaTax. If the credit invoice's balance is removed but the invoice remains closed (not voided), the AvaTax document is not voided.

EU transactions: Credit invoices won't display VAT Reverse Charge Notes if the original invoice was a reverse charge. The credit invoice references the original invoice, which contains the VAT Reverse Charge Notes.

Email template updates

Enabling Credit Invoices affects several email templates.

Payment Confirmation — Sent when a charge invoice is fully settled with a credit payment.

Payment Refunded — Sent when a refund is entirely credited to a credit balance.

Subscription Change — Sent immediately upon request. If the change results in both charges and credits and your site has PDF attachments enabled, the email includes two PDFs — one for the credit invoice and one for the charge invoice.

New Credit Invoice — Sent whenever a one-off credit invoice is issued. This doesn't apply to write-off credits, refunds, or subscription change credits. Customize this template to match your brand and messaging.

Issue a standalone credit invoice

One-off credit invoices can be issued directly from a customer's account in the Admin Console.

Available options when adding a credit:

• Note to Customer — Add a message for the customer that appears on the credit invoice
• Reason Code — Categorize the credit as general, service, or promotional to track its purpose
• Add Another Credit Adjustment — Define multiple credit adjustments at once
• Account Note — Add an internal note to the account before posting the invoice

You can preview the credit invoice or post it directly to the account.