All billing events create an invoice in Recurly. The invoice relates the charges or credits, transactions, and credit payments for the event.
Feature Highlight: Credit Invoices
- Align with accounting best practices by creating separate invoices for credits
- Benefit from new refund and invoice options to execute your business’ specific processes
- Streamline your customers’ experience by providing them easy-to-understand invoices
- Rely on a clear audit trail with updated Invoices Summary and Adjustments exports as well as a new Credit Payments export
Recurly sites created after May 8, 2018 UTC (May 7, 2018 5pm PT) automatically have the Credit Invoices feature.
Learn more about Credit Invoices and how to enable Credit Invoices on your existing Recurly site.
All of your customer invoices can be viewed in the Recurly Admin Console under Customers > Invoices.
The list of invoices is searchable by:
- Account code
- Account username
- Account email address
- Account first and last name
- Account company name
- Invoice number
- Invoice PO number
- Invoice Bill To address
- Invoice VAT number
- Invoice total
- Invoice discount amount
- Invoice tax amount
- Invoice recovery reason
The list of invoices can be filtered by:
- Invoice posted date
- Note that legacy invoices where the origin was purchase are included in the Charge filter and legacy invoices where the origin was refund are included in the Credit filter.
- Collection Method
The list of invoices can be sorted by:
- Invoice number
- Account display name
- Invoice posted date
- Invoice status
- Invoice total
To sort the list, click on the column header name.
Invoices have a type of either charge or credit.
- Charge invoices are regular invoices that only issued charges to the customer, for example in a purchase or renewal.
- Credit invoices are credit memos, also referred to as credit notes, that only issued credits to the customer, for example in a downgrade or refund.
Invoices created before the Credit Invoices feature was enabled on a Recurly site will have a type of legacy. These invoices will also include a note in the Invoice Info section of the Invoice Details page clarifying that the invoice was created prior to the Credit Invoices feature being enabled, to provide for clear expectations around invoice behavior.
Charge Invoice Statuses
Note that legacy invoices have the same statuses as charge invoices.
When an invoice is posted, it is initially in a Pending state. Pending means the invoice has not been paid and is not yet past due. Invoices that automatically attempt collection with the account's billing information will immediately move to a Paid or Past Due state, depending on the transaction result. Invoices with manual collection that have not yet received payment will stay in a Pending state until they are fully paid or the net-terms are reached.
The invoice is past due when the net-terms have been reached and the invoice has not been fully paid. Automatic collection invoices will move to Past Due immediately if the initial resulting transaction is declined. Manual collection invoices will move to Past Due 24 hours after the due date.
Note: If an account has a balance on it, or an account balance is added via creating an account credit, the balance can be applied to past due invoices via the UI, or via the following endpoints:
- GET https://recurly.com/developers/api/v2021-02-25/index.html#operation/get_account_balance
- PUT https://recurly.com/developers/api/v2021-02-25/index.html#operation/apply_credit_balance
- GET https://recurly.com/developers/api-v2/v2.29/index.html#operation/lookupAccountBalance
- PUT https://recurly.com/developers/api-v2/v2.29/index.html#operation/applyCreditBalance
The invoice is in a processing state when a payment transaction has been initiated, but has not yet come back as either successful or declined. This is common with ACH bank payments. After the transaction returns a response, the invoice will move to Paid if successful, or Past Due or Failed if declined (depending on your Dunning settings).
The invoice is paid once the customer has fulfilled the outstanding balance. The invoice will move to a Paid state immediately after post if the invoice had a zero balance due to zero amount charge adjustments, a full discount, or full payment by credit payments. Invoices with automatic collection will move to a Paid state immediately after post if the transaction was successful. Manual collection invoices with partial payments will not move to a Paid state until the full balance is paid.
The invoice is failed when it is considered uncollectable. Failing the invoice writes the invoice off as bad debt. Invoices can be failed directly, or will fail automatically at the end of the dunning cycle. For invoices created with the Credit Invoices feature enabled, failing the invoice will create a corresponding write-off credit invoice, bringing the failed charge invoice's balance to zero.
Credit Invoice Statuses
A credit invoice is open when it has an outstanding credit balance. Every credit invoice starts in an Open state.
The credit invoice is in a processing state when a refund transaction has been initiated, but has not come back as either successful or declined. This is common with ACH bank payments. After the transaction returns a response, the invoice will move to Closed if successful and no balance remains, or Open if declined.
Note that a Processing invoice will remove from the balance the amount covered by the processing transaction. Processing is not a closed state. If the transaction is declined, the credit invoice balance will increase. If there is a credit balance not covered by the processing transaction (original invoice was partially paid with credit payment), new charge invoices on the account during the processing period can use the additional balance as payment.
The credit invoice is closed when there is no outstanding credit balance. A credit invoice is only reopened if a credit payment from the invoice is voided, which occurs only if the corresponding charge invoice is failed.
Note that a Closed credit invoice could have had all of its balance used as credit payments, or a mix of credit payments and voided balance.
The credit invoice is voided when the credit invoice is deemed to be a mistake. Voiding the credit invoice means that none of the credit balance was used as payment or was refunded out as a transaction.
Once the Credit Invoices feature is enabled on your site, you will have access to the invoice-level origin attribute. This is the event that created the invoice and is helpful in understanding why the invoice was created, as well as providing reporting opportunities. You can see the origin of the invoice on the Invoice Details page, filter by origin on the Invoices index page, and see the origin in the exports, API, and webhooks. Note that the origin is called invoice_type in some exports.
Here are all of the possible invoice origins:
|Origin Display||Origin Code||Description|
|Purchase||purchase||A charge invoice from a subscription purchase or one-time purchase. This includes the purchase of a gift card.|
All legacy invoices that are not a refund invoice will have an origin of purchase.
|Renewal||renewal||A charge invoice from a subscription renewal. In this context, subscription renewal occurs at each billing cycle, not only at the end of the subscription term.|
|Immediate Change||immediate_change||A charge or credit invoice issued in an immediate subscription change.|
|Termination||termination||A credit invoice issued as a refund in a subscription termination, or a charge invoice issued as a final usage-based billing invoice in a subscription termination.|
|Refund||refund||A credit invoice issued from directly refunding a charge invoice.|
|Posted Credit||credit||A one-off custom credit invoice not against a charge invoice.|
|Write-Off||write_off||A credit invoice issued to write-off a failed charge invoice as bad debt.|
|External Refund||external_refund||A credit invoice issued due to a chargeback received from the Check Commerce ACH gateway.|
|Gift Card Redemption||gift_card||A credit invoice issued for a gift card redemption. Used for both Recurly gift cards and external gift card credits.|
Note a gift card purchase will have an origin of "purchase".
|Usage Correction||usage_correction||A credit invoice issued for a usage-based add-on's net-negative usage from a past cycle correction or current cycle over-correction.|
|Carryforward Credit||carryforward_credit||A credit invoice issued when the Credit Invoices feature is first enabled to transfer uninvoiced carryforward credits to the new credit invoice format. These invoices are NOT newly issued credit and represent previously issued credit balances.|
|Carryforward Gift Credit||carryforward_gift_credit||A credit invoice issued when the Credit Invoices feature is first enabled to transfer a specific gift card's uninvoiced carryforward credit to the new credit invoice format. These invoices are NOT newly issued gift card credit and represent the credit balance of previously issued gift card credit.|
|Line Item Refund||line_item_refund||A credit invoice issued when specific line item(s) are selected to refund on a legacy invoice.|
|Open Amount Refund||open_amount_refund||A credit invoice issued when a specific dollar amount is selected to refund on a legacy invoice.|
|Prepayment||prepayment||A charge invoice is issued for the specific dollar amount and a credit invoice is issued for an equivalent credit amount|
All invoices on your Recurly site, both charge and credit, pull from the same invoice number sequence, starting at 1000 and incrementing by 1. Please see below for additional options.
Customize Initial Number
If you would like your invoice numbering to start at a different number, contact Recurly Support.
Recurly does not allow you to add a visible prefix to your invoice numbering, but you can add a hidden prefix to segment your Recurly transactions within your payment gateway. This is helpful if you are using your payment gateway for multiple billing systems. To add a hidden prefix, go to Configuration > Site Settings and enter the prefix value under "Invoice Prefixing".
European Union Numbering
If you would like to have a separate invoice sequence for each European Union country, you can enable our Country Invoice Sequencing feature. Go to Configuration > Taxes > Tax Settings in the top right corner and enable "Country Invoice Sequencing" under "European Union VAT Settings". Learn more
The invoice display via the Admin Console, Hosted Invoice, or PDF will have the following elements:
Number and Collection
All invoices will have an invoice number and the date the invoice was posted.
- Charge invoices will also have net-terms and due date.
- Credit invoices issued against a charge invoice will list the applicable charge invoice(s).
The top left of the invoice will list your company information. The following fields will show, if filled out on Site Sittings under Configuration in the Admin Console.
- Company name
- Address 1
- Address 2
- Zip/postal code
- Phone number
- Billing contact email
- VAT number
- Registration number
All invoices will have a Bill To address for the customer. This defaults to the Billing Information address if the collection method is automatic, or the Account Information address if the collection method is manual. You can force the Bill To address to always use the Account Information address and only fallback to the Billing Information address when the Account Information is blank. To do this, go to Configuration > Taxes > Tax Settings and enable "Use Account Information Address for all Invoices" and save the page.
The following fields will show for the Bill To:
- First and last name
- Company name (will always come from the Account Information address)
- Address 1
- Address 2
- Zip/postal code
- VAT number
An invoice will have a Ship To address if you associated a shipping address with the subscription on the invoice or gave a specific line item a Ship To when issuing the invoice.
The following fields will show for the Ship To:
- First and last name
- Address 1
- Address 2
- Zip/postal code
- VAT number
Learn more about Shipping Addresses.
Each invoice will contain a table of line items with the following columns:
- Discount (column only shows if discounts are on the invoice)
- Tax (column only shows if tax is on the invoice and shows the rate only)
- Total (column only shows if tax is on the invoice)
The invoice display via the Admin Console, Hosted Invoice, and PDF will truncate line items after the first 500. However the Subtotal, Tax, and Total for the entire invoice will reflect the sum of all line items. If you need to retrieve the line items beyond the first 500, they can be obtained via the Adjustments Export
Total and Balance
The bottom right of the invoice will show the following invoice-level values:
- Tax (only shows if tax is on the invoice)
Between the Total and Balance you will see these balance-changing entries:
- Paid - Total of all payment transactions
- Credit Applied/Redeemed - Total of all credit payments
- Payment Refund - Total of all refund transactions
- Credit Voided - Portion of the credit balance that was removed
- Write-Off - Write-off amount
Quantity-Based Pricing Line Items
Recurly invoice line items for Tiered Volume and Stairstep pricing models are outlined below. The first charge is for the plan base fee. All subsequent charges are for the Add-On based on the pricing model and quantity. For more info, see Billing Models
A line item will be created for each tier. The Add-On name will have the range of units appended to the name. Example: Seats: 1-10
Line item are consistent with fixed price products and use the price per unit based on the subscriptions applicable tier.
There will be one line item that includes the add on name and the quantity purchased. The quantity for the charge will be 1 and the price will be the fixed price for the applicable tier.
The invoice display includes a "Payments" section with all transactions and credit payments that reduced the invoice's balance, including the date of the event and the amount.
Invoices have three 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 Console 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.
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.
Terms and Conditions
An extra notes section for payment terms, payment details, legal notes, or whatever you like! The title of this notes section will show on the invoice and cannot be changed.
VAT Reverse Charge Notes
VAT Reverse Charge Notes are configured on the Tax Settings page and are used for European Union reverse charge tax scenarios.
Learn more about VAT Reverse Charge Notes.
You can choose to include a PDF of the invoice in any email sent about an invoice. To enable PDF attachments for your site, go to Configuration > Invoice Settings > Emails Settings and select "Attach PDF" and save the page.
Additionally, you or your customers can download a PDF of any invoice by viewing the invoice in the Admin Console or the Hosted Pages.
PDF invoices are not customizable at this time.
When a customer subscribes, their first invoice is automatically included in the "New Subscription" email template. Subsequent automatic collection invoices are sent using the "Payment Confirmation" email template. Recurring invoices are not sent to customers when the total amount owed is $0.00. Note that manual collection invoices will always send out the "New Invoice" email template.
If emails are enabled for the plan, 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.
The line items Recurly creates on the invoice will be prorated in an immediate subscription change and include the option to prorate in an invoice refund. All proration is down to the second, even though the line item dates are to the day.
Learn more about immediate subscription change proration.
Recurly uses the collection method for charge invoices to determine whether to process payment immediately with the billing information on file or to only issue the invoice. Collection method can be set at the invoice level or the subscription level.
Posting an invoice with automatic collection will tell Recurly to immediately attempt to pay the invoice with the billing information on the account (e.g. credit card, bank account, PayPal, Amazon). With automatic collection, new subscriptions and the Purchases API endpoint will require a successful transaction in order for the invoice to post. Renewals and the Post Invoice API endpoint will post the invoice and process the automatic payment after the fact, sending the invoice into Past Due and the dunning cycle if a decline is returned.
Posting an invoice with manual collection will tell Recurly to issue the invoice, but not attempt any payment. You can manually enter an external payment later, or have the customer pay the invoice with an automatic method via our Make a Payment button on the hosted invoice.
Note that once an invoice is paid, or attempted to be paid, with the billing information on the account, the invoice converts to automatic collection. At this time it is not possible to record a manual payment on an automatic collection invoice or convert a charge invoice from automatic to manual collection.
To manually record an external payment, view the invoice in the Admin Console and enter the payment details in the left sidebar. A manually-paid invoice can be reopened.
Learn more about our Make a Payment option.
Modify Subscription's Collection Method
Changing the subscription's collection method will affect the collection method of the next charge invoice for the subscription. It will not change the collection method of any invoices that have already been issued for the subscription.
To change the collection method of the subscription, view the specific subscription on the Admin Console and select "Edit Subscription" in the Subscription Actions dropdown at the top right. Scroll down to the "Invoicing" section of the Edit Subscription page and select the new value in the Collection Method dropdown. Save the page. Changing the collection method will always apply immediately, even if "On next renewal" is selected under Plan Effected Date on the page.
When an invoice moves to a Past Due state, it starts the dunning cycle. For automatic collection invoices, this is after the first transaction decline for the invoice. For manual collection invoices, this is 24 hours after the due date of the invoice. Automatic and manual collection invoices have separate dunning cycles and separate dunning emails. Automatic collection invoices use the "Payment Declined" email template and manual collection invoices use the "Invoice Past Due" email template. Within your dunning settings, you can choose to fail the invoice at the end of the cycle, or leave it past due (note: if you have Account Updater enabled, Recurly will continue to run Account Updater on the account associated to the past due invoice and attempt to collect payment on that invoice in perpetuity).
Learn more about Dunning Management.
Learn more about Automated Transaction Retry Logic.
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 state and remove the invoice amount from the customer's account balance. Note that when the Credit Invoices feature is enabled, failing an invoice will create a corresponding write-off credit invoice, bringing the failed invoice's balance to zero. Stopping collection will also stop the dunning cycle, stopping all automated dunning emails and automated payment retries (automatic collection only) including ones performed by Recurly's Account Updater.
Once an invoice is failed, it cannot be reopened. This is also the case for manual collection invoices, due to the fact that the write-off credit invoice exists.
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 billing again.
Refunds are issued at the invoice level. To refund a customer, you can immediately change their subscription, refund a specific invoice, or choose to refund the last invoice while terminating their subscription. All of these events will create a refund credit invoice, which includes credit line items against previously-paid charge line items. Refunding will never reopen the original charge invoice. When refunding an invoice directly, you can choose to distribute the resulting credit balance as a payment refund (cash back on the customer's payment method), or leave it as a credit balance to be used as payment on future invoices.
To refund an invoice, go to the invoice in the Admin Console and select "Refund Invoice" in the Invoice Actions dropdown at the top right of the page.
Invoices created while in a sandbox environment 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.
Updated 6 months ago