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    

Invoice Settings

Invoices are created whenever a customer signs up for a subscription or a charge is invoiced. Right now Invoice Settings only cover invoice delivery, but we will be adding new invoice configuration options very soon!

Default Values

Customize your invoices with default terms and notes for your customers. These site level defaults can be overriden with custom invoice specific messages whenever you generate an invoice through the Admin or API.

Terms

Terms configuration applies only to manual invoices. All other invoices are always due "On-Receipt". If you are on our Professional, Elite, or Enterprise plans and sending manual invoices, you will see the Terms dropdown. Terms options are: On-Receipt, Net-10, Net-30, Net-60, or a custom number of days.

Terms and Conditions

Terms and Conditions is a notes section available to you for any details you would like to add. The section is ideal for notes about payment or contract terms. The title cannot be changed at this time. The section will only show on an invoice if there is text in the field.

Customer Notes

Customer Notes is another notes section available to you for any details you would like to add. This section is ideal for notes on invoice details or including a special message for the customer, like "thanks for your business". This section will only show on an invoice if there is text in the field and does not display a section title. Customer Notes are displayed at the bottom of the invoice in larger font than the Terms and Conditions.

Invoice Notes Example

VAT Reverse Charge Notes

If you are using Recurly's EU VAT feature for tax collection in the European Union, you will see a notes section called "VAT Reverse Charge Notes" that shows when a customer provides a valid VAT number and is located in a different country than your own. The notes will be pre-filled with a general statement that no VAT was applied to the invoice and the customer may be responsible for VAT. Merchants can edit this default message with any messaging they would like, as well as edit the section for custom invoice specific messages. To edit the default message, go to the Tax Settings page under Configuration > Taxes > Tax Settings button in the top right corner.

Email Settings

Invoices are sent in the body of Recurly's email templates. You can choose to attach a PDF of the invoice to the emails by enabling PDF attachments on the Invoice Settings page. There are 7 email templates that mention an invoice. Enabling PDF attachments will attach a PDF to all 7 templates.

Email Templates that support invoice PDF attachments:

  • New Subscription
  • New Invoice (Manual Invoice feature only)
  • Invoice Past Due (Manual Invoice feature only)
  • Payment Confirmation
  • Payment Declined
  • Payment Refunded
  • Payment Voided

Bill To Address

Select "Use Account Info Address for all Invoices" to force all customer invoices to use the Account Info Address, regardless of their payment method. The invoice address is displayed on the invoice in the "Bill To" section and is the address used for any tax calculations.

This feature is useful for merchants who:

  • Want to display a shipping or mailing address on the invoice
  • Need to calculate taxes based on a shipping or mailing address

When Account Info Address does not exist:

  • Automatic collection invoices will default back to the Billing Info, including Billing Info Address, Name, and VAT Number.
  • Manual collection invoices will still use Account Info, resulting in no address on the invoice.

Modification Enforcement

Some merchants may prefer to have their customers current on all payments before allowing a subscription upgrade or downgrade. Recurly allows this to be configured on your Invoice Settings page through two different options:

Require paid invoice and successful transaction on upgrades

Using this setting will ensure that any time a customer upgrades, or is upgraded through the admin console, the account has no past due invoices and the upgrade invoice is paid. An upgrade is defined as any increase in subscription price from changing the base price, changing the quantity, adding add-ons, or changing to a more expensive plan.

When a customer attempts to upgrade, Recurly will first check to see if there are any automatic collection invoices on the account. If so, Recurly will attempt collection on those past due invoices first. If they cannot be successfully collected, the upgrade will be blocked and the customer will get the following error: "Your account is currently past due, please update your billing information before changing your subscription." If the past due invoices are collected successfully, or the account didn't have any past due invoices, Recurly will attempt to collect on the upgrade. If the upgrade transaction declines, the upgrade will be blocked. If the upgrade transaction is successful, the upgrade will go through.

If you're using the API, please be sure to offer your customers a way to update their billing information in this scenario so that they can proceed.

Require paid invoice to downgrade

When downgrading an existing subscription, require that all invoices have been successfully paid in order to complete the downgrade. A downgrade is defined as any decrease in subscription price from changing the base price, decreasing the quantity, removing add-ons, or changing to a less-expensive plan. If any invoice is past due, the subscription will be kept on the original plan, and an error will be provided to the customer; "Your account is currently past due, please update your billing information before changing your subscription."

Please note that if you use this setting your customers will NOT be allowed to downgrade if they have a past-due payment.

Updated 4 months ago

Invoice Settings


Invoices are created whenever a customer signs up for a subscription or a charge is invoiced. Right now Invoice Settings only cover invoice delivery, but we will be adding new invoice configuration options very soon!

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.