An invoice relates charges, credits, and payments together. When a subscription is created or renewed, or a charge is created on the account, Recurly will sum the charges, discount or tax as appropriate, and send the invoice out for collection. Your subscribers are notified of successful or failed invoice collection via email.


Your invoices dashboard provides an overview of all invoices generated by Recurly. The filters on this view allow you to bucket invoices into different categories for easy sorting:

Every invoice generated within your Recurly site.
All invoices that are pending collection. Recurly has not yet received payments for these invoices.
Past Due
All invoices that attempted collection, but payment failed. These invoices will be retried automatically through the dunning process.
All invoices that have either experienced 20 declines, or has been through the dunning process without successful payment. These invoices will not be retried.
All successfully collected invoices.

You may search for an invoice on any of the following fields:


By default, your invoices will contain the following information:

Company Details
Company information configured in your site settings.
Customer Details
The account holder's name and address information.
Line Items
Invoice line items contain any subscription or add-on description, as well as quantities and descriptions for charges and credits applied to the invoice. For recurring charges, the line items will include the bill cycle covered by this renewal charge. If a discount is applied, then the amount discounted from any active coupons are identified by line item.
Subtotal of the line item amounts, after charges and credits are applied.
Total of the applicable taxes (as denoted by an asterisk in the line item rows). Customer must have a postal code and country for tax to be calculated. The customer address is taken from Billing Info for automatic invoices (e.g. - credit card, PayPal) and Account Info for manual invoices. See the full list of supported tax regions here.
Invoice total, after taxes and coupons.
Amount Paid
For refund invoices, the Amount Paid is not displayed.
Amount Due/Refund Amount
Amount currently due for the invoice. For refund invoices, the total refunded amount back to the customer
Credit to Account
The remaining credit applied back to the customer’s account from the current invoice.

Customer Details

The customer’s information on the invoice can include First and Last Name, Company, VAT Number, and Address. Company will always come from the Account Information. All other details will come from either the Account Information or the Billing Information depending on the invoice collection method and your site’s Tax Settings.

Automatic Collection

If the invoice collection method is automatic, the customer details will default to the Billing Information. If you want to always use the Account Information address, you can select “Use Account Information Address for all Invoices” under Configuration > Taxes > Tax Settings. If enabled, this option will use the Account Information on all automatic collection invoices. If the Account Information is missing an address, it will default to the Billing Information address.

Manual Collection

If the invoice collection method is manual, the customer details will always use the Account Information. If the Account Information is empty and Billing Information exists, the invoice will ingnore the Billing Information and will show blank customer details on the invoice.


Invoices will soon have two new notes sections. These notes will only show up on invoices if there is text in those sections. Notes can be configured to have site level defaults for all invoices, as well as be customized for specific invoices through the Admin or API. Site level defaults can be configured on the Invoice Settings page. Invoice specific notes are made when generating an invoice or creating/editing a subscription.

Terms and Conditions
An extra notes section for payment terms, payment details, legal notes, or whatever you like! The title of this notes section cannot be changed.
Customer Notes
An extra notes section for customer notes. This could be special details about the invoice, a note to say "thanks for your business", or whatever you like! The title of this notes section will not show on the invoice.


A subscription change with a timeframe of immediately will generate an invoice that displays additional line items that includes prorated tax amounts:

Prorating for remainder of subscription term
Charges from upgrading.
Remaining value for the subscription
Credit due to downgrade.



Subscription signups and one-time transactions are invoiced and collected upon immediately. Subscription renewals and manual charges are invoiced and then processed at the top of every hour.


An Open invoice can be manually marked as Closed by opening the invoice in your admin console and clicking the Stop Collection tab. This will give you two options:

Stop Collecting
Indicates that the invoice was not successfully paid for and that collection attempts should stop. This functionality is mostly used to halt the dunning procedures for an invoice.

Mark Paid
Indicates that the invoice was successfully paid for and that automated collection attempts should stop - this functionality is typically used to indicate that payment was received via another method and that revenue should be recognized.


When invoice collection fails, the invoice immediately enters a Past Due state and collection attempts will start based on your dunning management settings. Recurly will email the customer to alert them of the failed payment and automatically retry payment based on the card and error type. Reviewing the invoice details will display each collection attempt and reason for the payment decline. Recurly will stop trying to collect on an invoice after it has been attempted 20 times, or when the timeline in your dunning management settings has passed without successful collection.

Please Note: Stopping collection on an invoice will not automatically cancel the related subscription. The subscription needs to be canceled separately in order to stop the subscription from renewing again.

Invoice Numbers

All invoice start with number 1000 and increment by 1 with each invoice creation. If you need your invoices to start at a specific value, please contact Recurly support.

Sandbox Invoices

Invoices created while in sandbox will include a “TEST INVOICE” watermark. The watermark is only relevant to sandbox invoices – after moving to production, production invoices will not include the watermark.


When a customer subscribes, their first invoice is automatically included in the New Subscription email template. Subsequent invoices are sent using the Payment Confirmation email template. Recurring invoices are not sent to customers when the total amount owed is $0.00. An invoice email can be resent by clicking the Resend Last Email button on a specific invoice. You can attach a PDF of the invoice to all of your invoice related emails by enabling this feature on the Invoice Settings page.


PDF invoices are available to merchants and customers through multiple venues.

PDF invoices are not customizable at this time.

Invoices for Refunds and Voids

Recurly creates a new invoice for any refund or voided transactions, instead of reopening the original invoice. The second invoice makes it clear to your finance team that the previously collected amount has now been reversed. Transactions can be only be voided in a short period of time after the original successful transaction, but it is possible that the void can happen after your reporting period has closed, so the second invoice will make sure you see the change.

There are two ways to refund or void, line item refunds or open amount refunds. We recommend that you use line item refunds because the original line item identity is carried over to the refund invoice. Open amount refunds create custom refund amounts on an invoice level, so all line item identity is lost and a new general credit is created on the resulting invoice.

Invoices for refunds and voids have a type of “refund”, where as the original invoice will have a type of “purchase”. All successful refund invoices will have a state of “paid”.

How to Refund or Void

To create a refund or void a transaction, you can either select the original purchase invoice or the successful transaction. If you are on the invoice page, you will see the option to refund in the sidebar. If you are on the transaction details page, you will see a button to refund the transaction in the top right corner of the page. Both methods will take you to the same refund page.

Initiate Refund

Refundable Amount and Credits

Refunds defined by invoice line items provide greater accuracy in accounting and taxes. When you consider an invoice with charge and credit line items, the full value of the invoice is the sum of the charges. Therefore, the total refundable amount of an invoice is the total of all the charges, not the transaction amount.

When credit line items exist on an invoice, a partial refund could refund credit back to the account first or a transaction giving money back to the customer first. Recurly defaults to “credit first” to favor the merchant.


An invoice has a $10.00 charge and a -$5.00 credit. The total and transaction for the invoice was $5.00. The total value of the original invoice is $10.00, so a full refund amount would be $10.00.

If you want to refund $4.00, you have the option of refunding credit to the account or a transaction giving money back to the customer.

If you refund $6.00:

Line item refunds

Line item refunds allows you to select the specific line items to refund from the invoice, including the quantity and whether or not you want to prorate the amount based on the current period (Note: unless the ‘prorate’ option is selected, the full amount will be refunded by default). We handle the calculations for any discount or tax if applicable for the refund, which you can verify on the preview page before confirming the refund. The feature is available in your Admin Panel and also via API.

Select Line

Once you confirm and the refund is successful, we create a refund invoice so that you can pass along to your customer or store internally for your own records.

Refund Invoice

Open amount refunds

Open amount refunds allows you to specify the amount you’d like to refund irrespective of a particular line item. This may be case when you need to refund a partial amount of a line time that isn’t tied to the prorated amount, or simply a partial refund for a random amount due to special circumstances. Either way, Recurly let’s you set the custom amount for the refund as along as it does not exceed the amount of the transaction, or the amount remaining that’s available to refund. The feature is available in your Admin Panel and also via API.

Open Refund

Also for open amount refunds, we calculate in the tax if it was applied on the original invoice for you as part of the amount that you specify. Once the open amount is is confirmed, we provide you with the refund invoice that references the original invoice number, which you pass to your customer or store for your own internal records.

Open Invoice


If a paid invoice has a transaction that has not settled yet, a refund will trigger a void. The transaction will be voided and a new refund invoice will be generated. The new invoice will be a negative invoice with a state of “paid” and an invoice type of “refund”, but the invoice itself will display “VOIDED” in purple with a footnote of “Refund of invoice #1001 due to voided transaction”. Note that the original invoice will still be a postive invoice with a state of “paid” and an invoice type of “purchase”.

You will need to do a full refund when attempting to void. A prorated void will display an error. You can only void the full amount of the original invoice because the associated transaction has not settled.


Refunds and voids will now have three webhooks. The first is the normal successful_refund or void_payment transaction webhooks. These will be accompanied by two webhooks for the associated invoice: new_invoice, closed_invoice.

Payment History

When viewing invoices in the admin console, each invoice will include a “Payment History” section that references all transactions and other invoices that are related to the invoice. For example, if an invoice is successfully paid then later refunded, the Payment History for that invoice will link to the original transaction, as well as the related refund invoice.

The Payment History is only available when viewing an invoice in the Recurly admin console. This is strictly an internal tool to help merchants tie related transactions/invoices together, and will not be displayed on customer-facing invoices.

Subscription Changes

Recurly does not reconcile invoice payments with subscription requests. If a subscription has a refund in the current billing cycle, updates with an effective date of “Immediately” will always credit the customer as if the refund never existed. Updates with an effective date of “On next renewal” will not have this problem.