The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    


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.

New Refreshed Invoice Design - February 8, 2018

  • Refreshed look and feel
  • New streamlined notes treatment
  • New "Payments" section to show how the invoice was paid
  • Invoice number moved to the top
  • Refund invoices now say "Refund" at the top have a green status color, instead of purple
  • Invoices with credits against previously issued charges will now show "Refunded Invoice #:" at the top of the invoice with the number of the original invoice.
  • Released February 22, 2018: The Tax column changed from an amount column to a rate column to bring our invoices in line with tax best practices and better support of multi-rate invoices. Non-taxed line items will show a 0% rate instead of an asterisk calling out taxable line items.


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 manual invoices that have not yet reached the end date of their collection terms.

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 have been through the dunning process without successful payment. These invoices will not be retried.


All successfully collected invoices.

Invoice Search

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

  • Account code
  • Company name
  • First name
  • Last name
  • Email address
  • Username
  • Address
  • Amount
  • Invoice number
  • PO number


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. 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 ignore the Billing Information and will show blank customer details on the invoice.


Invoices have two notes sections. These notes 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 include prorated 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.

If the customer is unable to pay through an online method connected to Recurly, you can have the customer pay through a different method (e.g. - check). To note the external payment in Recurly, click Mark Paid in the Invoice Actions dropdown on the invoice details page. This will move the invoice to a Paid state. Note that it will not create a transaction associated with the paid status.


A Manual invoice can be manually paid by Recording an Offline Payment on the invoice details page.

Stop Collection

If a customer is not going to pay an invoice and it needs to be written off, you can Stop Collection from the Invoice Actions dropdown at the top right of the invoice details page. This action will move the invoice to a failed status and removes the amount from the customer's account balance. Stopping collection will also stop the dunning cycle, stopping all automated dunning emails and automated payment retries (automatic collection only).


An invoice enters the dunning cycle when it's state moves to Past Due. For an automatic collection invoice, this is after the initial payment transaction fails. For a manual collection invoice, this is when the net terms are passed. Recurly allows you to configure separate dunning schedules for your automatic and manual collection invoices.

By default, dunning settings will automatically fail an invoice at the end of the dunning cycle if the invoice has not been paid. A failed invoice is Recurly's way of writing it off as bad debt, removing the owed balance from the customer's account. You can change your dunning settings to never auto-fail the invoice and leave the invoice past due. When you change the invoice dunning setting, all invoices currently in dunning (in a past due state), will still either fail or stay past due based on the previous setting, but new invoices entering dunning will start to follow the new setting. This is due to the fact that dunning settings are versioned to make sure an invoice currently in a dunning step doesn't all of a sudden get a new schedule.

To learn more about dunning and how it affects payment retries and email notifications, read our Dunning Management documentation.

Please Note: Stopping collection (failing) 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.

  • Admin Invoices Overview and Invoice Details pages
  • API
  • Hosted Account Management Invoices table and Invoice Details pages
  • Invoice related Email Templates

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 Invoice Actions dropdown. 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.

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.

  • Credit first will result in a $4.00 credit on the account, no money back to the customer.
  • Transaction first will result in a $4.00 transaction returning money back to the customer.

If you refund $6.00:

  • You could choose credit first and put a $5.00 credit on the account and a $1.00 transaction back to the customer.
  • Or you could choose transaction first and give $5.00 of money back to the customer and $1.00 of credit on the account.

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.

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.

Open amount refunds

Open amount refunds do not maintain line item identity

We recommend using Line Item Refunds when you can because Open Amount Refunds refund at the invoice level.

  • This means the resulting refund line item has no subscription, product code, accounting code or tax code identity.
  • Due to this, open amount refunds with tax will back out the tax and use a basic Avalara tax code of P0000000 (Tangible Personal Property), which can cause rounding issues or incorrect tax amounts due to missing tax rules.

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.

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.

Terminating and Refunding Subscriptions

Similar to a line item or open amount refund, when a subscription is terminated and refunded a refund invoice will be created for the appropriate amount.

When terminating and refunding, Recurly refunds the most recent invoice associated with that subscription UUID. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will create a refund invoice and apply the credit back to the customer's account.


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 positive 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.

  • If you issue a refund and then need to change the subscription in the same billing cycle, Recurly recommends you make the change "On next renewal".
  • If you make a subscription change and then need to issue a refund in the same billing cycle, Recurly recommends only refunding the subscription change invoice since the previous invoice was already been refunded through any credit applied to the subscription change invoice.


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.