Before you enable Credit Invoices
- Your Recurly site must have the Only Bill What Changed feature enabled in order to have Credit Invoices enabled.
- If you are using our NetSuite integration please wait to enable the feature on a production mode site until we confirm the NetSuite integration is ready.
- If you are using an integration built by a 3rd party, not Recurly, please review it to see if it would be affected by the below changes. Talk to the 3rd party to see if you need to upgrade your integration.
- Please review this documentation and Go Live checklist
Recurly sites created after May 8, 2018 UTC (May 7, 2018 5pm PT) automatically have the Credit Invoices feature.
Recurly now supports the issuing of credit memos / credit notes through our Credit Invoices feature.
- Separate invoices for credits
- New credit payment object to track credit balance use
- Ability to issue one-off credit invoices
- Option to refund to credit balance instead of payment method
- Option to refund credit payments back to their original payment method
- Option to record an external refund transaction when an automatic transaction is no longer refundable
- Option to refund the remaining portion of a prorated charge
- Failing an invoice now issues a write-off credit invoice
- Deleting a credit now leaves an audit trail through the void credit invoice option
Before you enable the Credit Invoices feature on your production Recurly site, please confirm you have taken the following steps:
- Read this documentation page.
- Enable the Only Bill What Changed feature, which Credit Invoices is built on top of.
- Enable the Credit Invoices feature on a sandbox site and test your billing flows and reporting!
- Update your integration with Recurly to account for the API changes.
- Update your integration with Recurly to account for the Webhook changes.
- Update your internal reporting to account for the Export changes and how existing uninvoiced carryforward credits will be transitioned.
- Prepare for the new email template and logic changes to existing templates.
- Once you are ready, enable the Credit Invoices feature on your production site.
A credit invoice is Recurly's version of a credit memo or credit note. Once the Credit Invoices feature is enabled on a Recurly site, any credit issued to a customer is given it's own invoice. Separating issued credits from issued charges provides clean gross numbers for your finance team, tax compliance, and simplifies the invoice for your customer.
Credit invoices have a negative total and balance and only include credit adjustments. Charge invoices have a positive total and balance and only include charge adjustments. Both charge and credit invoices share the same invoice number sequence.
Credit invoices have four possible statuses: Open, Processing, Closed, or Voided
- Open means the credit invoice still has a balance.
- Processing means there is an ACH/bank account refund transaction processing. The credit invoice balance will be reduced by the refund transaction amount. If the transaction succeeds and there is no additional balance, the credit invoice will close. If the transaction declines, the credit invoice will move back to open and the amount will remain as a credit balance on the invoice.
- Closed means there is no credit balance remaining.
- Voided means the credit invoice was issued by mistake and has been canceled.
Credit invoices come in three different versions:
A credit invoice with Credit at the top indicates that the credit does not correspond to any charges. This is what we often refer to as custom or one-off credit. This credit may have been issued as a service, promotional, or gift card credit. You will never see discounts or taxes reversed on a Credit credit invoice because there are no charges to pull discounts or taxes from.
When a Credit credit invoice is issued, Recurly will send your customer the New Credit Invoice email. If you would like to customize this email template or disable it for your site, go to Configuration > Emails.
A credit invoice with Refund at the top indicates that the credit is a reversal of previously issued charges. A Refund credit invoice is created when a subscription is changed immediately and prorated credits are issued, or refunding an invoice directly or in a subscription termination.
When a Refund credit invoice is issued, emails are sent based on the event. In a subscription change, the Subscription Change email is sent and will include the credit invoice as a PDF attachment, along with the charge invoice, if PDF attachments are enabled on the site. In an invoice refund or subscription termination and refund, the Payment Refunded email will be sent to the customer.
Recurly Now Keeps You From Over Crediting
With the Credit Invoices feature, Recurly now tracks all credits issued against a charge and does not allow you to credit more than the original charge amount.
For example, if you refund the last invoice of an active subscription and then downgrade the subscription, Recurly will not issue credit to the customer in the downgrade because the credit was already issued in the refund. Or vice versa.
A credit invoice with Write-Off at the top indicates that the credit was issued to write-off charges on a corresponding failed invoice. Once the Credit Invoices feature is enabled on your site, failing an invoice will always issue a write-off credit invoice to bring the failed invoice's balance to zero.
The write-off credit invoice.
The failed charge invoice.
When a credit invoice's balance is used as payment on a charge invoice, a credit payment is created to record the amount that reduced the balance of both the credit and charge invoice. Credit payments are visible on the invoice and can be exported in the Credit Payments export to see an audit trail of how credit balances were reduced, when, and by how much.
A charge invoice paid with a $20 credit payment and $30 credit card transaction.
The credit payment object in Recurly is used to track the use or removal of credit balances. This is primarily the use of an open credit balance as payment on a charge invoice, but does include the record for balance write-offs, credit balance removal, and when a credit payment is refunded back as a cash transaction. All of these event types are called "Actions". The table below details what each action means. Actions can be viewed from the Credit Payments export or via the API.
The payment action is a normal credit payment that took all or a portion of a credit invoice balance and applied it as payment to a charge invoice.
The gift card action is also a normal credit payment, but the credit invoice the amount is from has an invoice origin of "gift_card". This action is useful in tracking what invoices were paid with gift card credit.
The write-off action is used to take the balance of a write-off credit invoice and apply it to a failed charge invoice, reducing the failed invoice balance to zero.
The reduction action is used to remove a credit balance from a credit invoice.
The refund action is used when a credit payment is refunded as a refund transaction. This event creates a new credit payment that records the id of the original credit payment that was refunded and the id of the new refund transaction that the value was converted to.
Previously Recurly issued credits on the same invoice as charges, treating the issued credit as a credit payment at the same time. If not all of the credit was used, a new uninvoiced credit was created on the account for the remaining balance. These "carryforward" credits are no longer created once the Credit Invoices feature is enabled, but some will likely still exist uninvoiced on your customer accounts.
To transition existing uninvoiced carryforward credits on your customer accounts to the new credit invoice structure, Recurly will put all uninvoiced carryforward credits on an account on to a new credit invoice as soon a the Credit Invoices feature is enabled. This credit invoice will have a special origin of carryforward_credit to help you identify at the invoice level that the credit invoice represents the balance of already issued credit, not new credit. The invoice will include this specific customer note: "This invoice represents the remaining credit balance of previously issued credits."
It is necessary to transition these uninvoiced carryforward credits to a credit invoice in order for their value to be used as credit payments on future charge invoices.
Any uninvoiced credits on the account that have yet to be issued to the customer, so they are not carryforward credit, will be issued on a regular credit invoice at the next invoicing event. For example, if a one-off custom credit is sitting on the account uninvoiced, when the Credit Invoices feature is enabled, the credit adjustment will remain uninvoiced until the customer's renewal or next billing event. The credit will not be put on an origin carryforward_credit invoice.
Jump In Invoice Numbers
When you enable Credit Invoices on your Recurly site, you may see a jump in invoice numbers due to the fact that Recurly goes through each account and puts any uninvoiced carryforward credits on a new credit invoice with origin of carryforward_credit.
With the Credit Invoices feature, we added a new attribute at the invoice level called origin. This is the event that created the invoice and is helpful in understanding why the invoice was created, as well as provides new 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 exports call the origin invoice_type in some exports, since it is using an existing column.
Immediate subscription changes for either a downgrade or upgrade will now issue credits separately from charges. This means a subscription change could result in a charge invoice, a credit invoice, or both. For example, if the plan of the subscription is changed from Silver to Gold, a credit invoice will be issued for the Silver credit and a charge invoice will be issued for the Gold charge. While two invoices are issued, the customer will still get one Subscription Change email. If you attach PDF's to your Recurly emails, the customer will see two invoice PDFs attached, one for the credit and one for the charge.
Previously in Recurly, you could put a custom credit on a customer's account, but you could not invoice that credit without invoicing a charge at the same time. Now you can issue credits on their own credit invoice.
To issue a one-off credit invoice, go to the customers account and click on Add Credit. You will see some new options:
- Add a message for your customer to the credit invoice in the Note to Customer section.
- Set a Reason Code of general, service or promotional to start tracking why the credit was issued.
- Define multiple credit adjustments at one time by clicking on Add Another Credit Adjustment.
- Add an internal note to the account in the Account Note section before posting the invoice.
- Preview the credit invoice before posting or post the credit invoice to the account right away.
Posting a credit invoice through the Add Credit flow in the Recurly Admin Console will not invoice any currently uninvoiced charges or credits on the account.
It is no longer possible to create an uninvoiced credit adjustment on the account through the Recurly Admin Console. All one-off credits are issued on an invoice immediately. You can still create uninvoiced credit adjustments on the account through our API, which will get picked up at the next invoicing event and issued on their own credit invoice.
Previously refund invoices were negative charges and only accounted for refund transactions in the total. Now refunding an invoice will create a refund credit invoice with credit adjustments. If the original invoice was paid with credit, the refunded credit will transfer as a portion of the credit balance on the issued refund credit invoice.
Example: Original invoice was $100, paid with $20 of credit payment and an $80 credit card transaction.
Refunding the entire invoice to its original payment methods will create a refund credit invoice with:
- Total of ($100)
- Refund transaction of $80
- Credit Balance of ($20)
Refunding an invoice now includes the following new options:
Now if you issue a prorated refund, you can go back to the original invoice and refund the remaining amount. This option is available for refund credit invoices issued after the Credit Invoices feature was enabled. Legacy refund invoices will not have this option.
When talking to customers, we learned that some of you are creating custom credits in order to refund an invoice originally paid with a payment method (e.g. - credit card) as a credit balance on the account. Now you have the option to refund to Credit in the refund flow on the Refund Preview page. Refunding to credit will issue a refund credit invoice with a Credit Balance that equals the Total Refund. Future invoices on the account will draw from the credit balance until the credit invoice is closed.
Going back to our example above: If the original invoice was $100, paid with $20 of credit payment and an $80 credit card transaction, then refunding the entire invoice to credit will create a refund credit invoice with:
- Total of ($100)
- No refund transactions
- Credit Balance of ($100)
Have you ever refunded an invoice in Recurly and noticed that an uninvoiced credit was put on the account? And then maybe you deleted that credit and refunded an older invoice in order to get the cash back to the customer? This is a case where the invoice being refunded was paid partially or fully with credit. Now you have an easier way for you to get money back on the customer's card.
If an invoice was paid with a credit payment, and that credit payment ultimately came from a refundable transaction, we'll refund the credit payment as a transaction for you. When issuing a refund through the Admin Console, you'll know there are refundable credit payments on the original invoice if you see the Refund Credit Balance with Transaction checkbox. Check the box to see the invoice preview adjust to include additional pending refund transactions.
- Subscribe your customer to Gold for $50.
- Immediately downgrade your customer to Silver for $40. This will issue a refund credit invoice with an open balance of ($10).
- Upgrade the customers subscription by adding an add-on for $15. This will pick up the ($10) credit balance on the invoice in step 2.
- Let's say your customer experienced an issue with the service related to the add-on and you want to give them a cash refund of the $15 upgrade fee. When you refund the invoice in step 3, you will see the option to Refund Credit Balance with Transaction. Without this option, the refund invoice will create a refund transaction of $5 and leave a credit balance of ($10). With the option selected, two refund transactions will be created, one for $5 and one for $10, reducing the refund credit invoice balance to $0 and giving the customer $15 in cash.
While refunding credit payments to their original payment method can create multiple refund transactions, one Payment Refunded email will be sent to the customer, summarizing the payment refund received.
The Recurly system refunds specific credit card transactions. This keeps a clean audit trail of transactions. When a credit payment is refunded, Recurly looks at the credit invoice that the credit payment originated from and the original charge invoice the credit invoice was against. If that original charge invoice has a refundable transaction, the credit payment can be refunded and a refund transaction is created against that original purchase transaction. The relationship between the credit payment and refund transaction that took it's place is captured in the credit payment object. When a credit payment is refunded, a new credit payment is created with an action of refund. Additionally, the credit payment includes the id of the credit payment it is refunding and the id of the refund transaction that took its place. These data points are found in the Credit Payments export and in the API.
Recurly will now create a refund credit invoice when the refund transaction declines. Previously the refund invoice would be blocked due to the transaction error. This was problematic because if the customer needs a refund, they will get a refund eventually in some way, but Recurly was not able to record it. Now we have multiple options when a refund results in a declined transaction or you issued the refund by mistake.
By default, if a refund results in a declined transaction, Recurly will create the refund credit invoice and keep the amount of the transaction as part of the credit balance on the invoice. If the customer will have future purchases, the balance will automatically be used as payment.
If a refund credit invoice has a refundable balance, you will see the option to Refund Credit Balance in the left sidebar of the Invoice Details page. Select Original Payment Method to retry the transaction. You can retry up to 5 times. We limit the number of retries because it is unlikely a refund transaction will work on a retry in general, and each declined refund transaction incurs transaction fees.
Sometimes it is no longer possible to refund the original transaction. In this case, you can refund the customer through a means external to Recurly and record the refund transaction in Recurly in order to close out the refund credit invoice. To record an external refund transaction, go to the Refund Credit Balance option in the left sidebar of the Invoice Details page and select External Refund. You can select the payment method, date and record an internal note for your external refund transaction.
If the refund was issued by mistake, or you decided to cancel the refund due to the decline, you can void the refund credit invoice. Voiding a refund credit invoice will make the original charge invoice refundable again. Note that you cannot void the refund credit invoice if a portion of the balance was used as a credit payment on another invoice, or if the balance was partially refunded with a refund transaction.
When a charge invoice is failed directly or at the end of the dunning cycle, a matching write-off credit invoice is created to reduce the failed invoice's balance to zero. The write-off invoice includes credit adjustments that are exact reversals of the charges on the failed invoice. This includes the descriptions, taxes and discounts. These credit adjustments will have a credit reason code of write_off. Additionally, the credit invoice will have an origin of write_off, so you can what was a write-off at every level.
As soon as the write-off invoice is created, it's balance is applied to the final invoice via a credit payment with action of write_off. With this application, the write-off credit invoice is immediately closed at the time of collection.
Failing an invoice created before the Credit Invoices feature was enabled on the site, legacy invoices, will not create a write-off credit invoice.
Once the Credit Invoices feature is enabled, it will no longer be possible to reopen a manual collection failed invoice. You can still reopen a manual collection paid invoice, but not one in a failed state.
Failing an invoice with a credit payment
Now when you fail an invoice with a credit payment applied, the credit payment will be voided and the value put back on the credit invoice the credit payment came from. This will reopen the credit invoice. When a credit invoice is reopened, you will see an activity on the account and a webhook will be sent out.
Sometimes a credit is issued by mistake and needs to be deleted. Previously in Recurly, an uninvoiced credit could be deleted and would remove all history of the credit existing. Credits can no longer be deleted, but the credit balance can be removed, leaving an audit trail.
If a credit invoice still has a full balance, meaning no credit payments or refund transactions have reduced the balance, the credit invoice can be voided. Voiding the credit invoice moves it into a voided state. Additionally, the credit balance is removed by the creation of a credit payment with the action reduction that is from and applied to the credit invoice. To void a credit invoice, go to the Invoice Details page for the invoice and in the Invoice Actions dropdown, select "Void Credit Invoice".
Full credit invoice voided.
If a credit invoice only has a partial balance remaining, you cannot void the credit invoice, but you can still void the credit balance. When you void the credit balance, a credit payment with action reduction is created for the amount of the remaining balance and applied to the credit invoice. Since a portion of the balance was used, the credit invoice moves to a closed state. To void a credit balance, go to the Invoice Details page for the invoice and in the Invoice Actions dropdown, select "Void Credit Balance".
To report on removed credit balance, export the Credit Payments export and filter the action to refuduction. The credit payments with original invoice status of voided are the clean credit removals. The credit payments with original invoice status of closed are the unique situations where a portion of the credit balance was used and a portion removed. The credit payment amount shows you what portion was removed.
To keep your accounting clean and allow Recurly to accurately reverse discounts and taxes on credits, Recurly now tracks which charge each credit is from, and ensures that the sum of all credits is never greater than the charge they are against. This change will affect merchants with the following scenarios.
If you are failing, or refunding, an invoice in order to then recreate it due to incorrect taxes or an adjustment in the amount the customer will pay, any following immediate subscription changes for the invoice's billing cycle will not issue any credit. This is due to the credit invoice issued in the failing, or refund, fully crediting the last charges for the subscription. This happens because the recreated invoice is not associated with the subscription, so the immediate subscription change cannot find charges that can be credited.
If this happens and you need to issue the customer credit, we recommend refunding the recreated charge invoice instead of issuing a one-off credit on the account. This will ensure that the credit adjustment issued backs out taxes and discounts correctly. A one-off credit will never reverse taxes or discounts.
If you are using the Postpone Subscription feature to extend a subscription cycle and are also allowing the customer to immediately change their subscription after the extension, the resulting change will not include credit for the extension period like it did previously. This happens because there are no charges for the extended time, so the subscription change can only credit for the portion of the pre-extension charges that have not been credited yet.
If you are issuing a one-off charge invoice for the extended cycle, the subscription change will still not issue credit for the extension. This happens because the one-off invoice for the extension is not related to the subscription.
If this happens and you need to issue the customer credit, we recommend refunding the one-off charge invoice for the extension instead of issuing a one-off credit on the account. This will ensure that the credit adjustment issued backs out taxes and discounts correctly. A one-off credit will never reverse taxes or discounts.
Refund and write-off credit invoices will reverse taxes if the corresponding charge invoice collected taxes. One-off credit invoices will never reverse taxes because the credits are not linked to any charges.
If you are using our Avalara AvaTax integration and commit paid invoices, you will see that Recurly will commit every credit invoice at the time it is issued. If you void a credit balance, Recurly will void the committed document in AvaTax. If the credit invoice's balance is removed, but the invoice is closed, not voided, Recurly will not void the committed document in AvaTax.
If you are taxing in the EU, note that the credit invoice will not show VAT Reverse Charge Notes in the case where the original invoice was a reverse charge. The credit invoice will reference the original invoice, which has the VAT Reverse Charge Notes.
The Credit Invoices feature comes with a few changes to your email templates:
The Payment Confirmation email will now be sent when a charge invoice is paid completely with credit payment, showing the customer they paid with credit.
The Payment Refunded email will now be sent when a refund is entirely applied to a credit balance, showing the customer they received a refund in the form of credit.
- The Subscription Change email will now send at the time of request, meaning at renewal changes will send the email immediately, showing the customer they have a pending change and what that pending change is.
- Additionally, the email will include two PDF attachments, one for the credit invoice and one for the charge invoice, in the event the immediate subscription change issued both charges and credits and your site has PDF attachments enabled.
- The default template body will only show the charge invoice, unless only a credit invoice is issued, which will then show the credit invoice in the body.
When the Credit Invoices feature is enabled on your Recurly site, the New Credit Invoice email is added to your email templates and is enabled by default. This email goes out whenever a one-off credit invoice is issued. This email does not go out for write-off credits, refunds or subscription change credits. You may want to disable this email once the feature is enabled and customize the email template before re-enabling it.
Enabling Credit Invoices will add the new Credit Payments export and remove the deprecated Invoices export. Please contact Recurly support when you are ready to update your Automated Exports for Credit Invoices and we will make this export addition and removal for you.
The Invoices export is deprecated and removed once the Credit Invoices feature is enabled on your Recurly site. We recommend using the Adjustments export to get line item and invoice level data.
The Invoices - Summary export will now include rows for both charge and credit invoices. For example, in an immediate change where the customer upgrades from Silver to Gold and receives both credits and charges, the Invoices - Summary export will have two rows. One row for the credit invoice for the refunded Silver and one row for the charge invoice for the Gold fees. Additionally, now that charges and credits are not mixed, the invoice_subtotal_before_discounts will give the gross charges or credits on the invoice, as well as invoice_discount for the gross discounts, and tax_amount for the gross taxes.
In the Admin Console, you can pre-filter the Invoices - Summary export to just charge invoices or just credit invoices. Once a type is selected, you can filter further down by status.
Note that legacy invoices, which are invoices created before the Credit Invoices feature was enabled, are grouped under the type "Charge". We grouped legacy invoices under type charge because legacy invoices have the same statuses as charge invoices.
The invoice_type column previously only included values of purchase and refund. This column is now showing the new origin attribute of the invoice, which is the event that created the invoice. We did not change the column header in order to avoid breaking customer integrations with the exports. See a full overview of what each invoice origin means.
The invoice_doc_type is a new column that represents the new type attribute of invoices. An invoice can have a type of charge, credit or legacy. All invoices created before the Credit Invoices feature was enabled will have an invoice_doc_type of "legacy". All invoices issued after the feature was enabled will have a type of either "charge" or "credit". Charge invoices only contain issued charges. Credit invoices only contain issued credits.
The invoice_balance is the current balance of the charge or credit invoice. Legacy invoice will never have a balance value.
The invoice_balance_modified_at is the date and time of the last credit payment or transaction that reduced or increased the balance. Note that charge invoice balances are reduced by credit payments and or purchase transactions, and credit invoice balances are reduced by credit payments and or refund transactions.
A balance can be increased in two scenarios:
- A processing bank account (ACH) transaction reduced the invoice balance, but the transaction resulted in a decline, increasing the balance.
- A credit invoice was used as payment on a charge invoice. The charge invoice was then failed, voiding the credit payment and returning the amount to the credit invoice, moving it from a closed to an open state.
The invoice_refundable_amount shows what is left to refund on a charge invoice. If the value is zero, the invoice has been fully refunded.
The big change with the Adjustments exports is that it will no longer include carryfoward charges and credit balance credits moving forward. The export will now only include issued charges and credits. All balance change events are in the Credit Payments export and Transactions export. The balance amount and date it last changes is in the Invoices - Summary export.
Like the Invoices - Summary export, the invoice_type will now reveal an extended set of origin events that created the invoice. See the table above for full details.
The adjustment_credit_reason_code will show you at a high level why the credit was issued. Recurly sets the credit reason code in all crediting events, except when one-off custom credits are created. If you see a credit adjustment with origin of "credit", the associated credit reason code was set by your own team. Note that the default for custom credits is "general". The other custom credit options are "promotional" or "service".
The default value for a one-off custom credit adjustment.
A possible value for a one-off custom credit adjustment. Useful in tracking credits issued due to business issues or customer happiness.
A possible value for a one-off custom credit adjustment. Useful in tracking credits issued as part of a promotion.
Set by Recurly on a credit adjustment issued against a charge adjustment where the original invoice was paid. This happens when refunding an invoice directly, issuing credit in an immediate subscription change, or refunding an invoice in a subscription termination.
Set by Recurly on a credit adjustment issued against a charge adjustment where the original invoice was failed to stop collection. This happens whenever a charge invoice is failed directly or at the end of the dunning cycle.
Set by Recurly on a credit adjustment with origin of "gift_card" or "external_gift_card" to identify your issued gift card credits. This happens when a Recurly gift card is redeemed or an "external_gift_card" origin credit adjustment is created through the API.
The adjustment_refundable_amount shows the amount left on the charge adjustment that can be credited. If the value is zero, the charge adjustment has been fully credited. If the value is non-zero, credits can be created against this charge in a refund or subscription change event. Credit adjustments and adjustments from legacy invoices (before Credit Invoices was enabled on your site) will not have a refundable amount value.
We have a brand new export called Credit Payments were you can find all of the credit payment events that changed the balance on your issued credit invoices, or the charge invoices they applied to. Each row represents one credit payment.
The Accounts Receivable export will not include rows for credit invoices. Additionally, we've added two balance columns to show you the current balance of the invoice.
The invoice_balance is the balance of invoices created after the Credit Invoices feature was enabled on your Recurly site. This balance column will accurately reflect partial manual payments and will include any credit payments.
For legacy invoices, invoice created before the Credit Invoices feature was enabled on your site, you will need to continue to look at the invoice_total column.
The invoice_balance_modified_at will show you the date and time of the last credit payment or transaction that adjusted the balance of the invoice.
The Revenue Recognition Schedules export will include rows for issued credit adjustments, including those created for a write-off invoice. To account for this and the new credit invoice statuses, we have made the following updates to the filtering and columns.
In the Admin Console, you can pre-filter the Revenue Recognition Schedules export to just charge invoice adjustments or just credit invoice adjustments. Once a type is selected, you can filter further down by status.
Note that legacy invoice adjustments, which are invoices created before the Credit Invoices feature was enabled, are grouped under the type "Charge". We grouped legacy invoice adjustments under type charge because legacy invoices have the same statuses as charge invoices.
The invoice_origin column will allow you to see the event that created the invoice the adjustments were issued on. invoice_origin is equal to invoice_type in the Invoices - Summary and Adjustments exports. Because this column was new to the Revenue Recognition Schedules export, we were able to give it its new proper attribute name, origin, without breaking customer integrations.
Use the invoice_origin column to filter out write_off credit adjustments.
All API updates for the Credit Invoices feature are on version 2.10.
- Ruby version is 2.15.2. Also see:
- Java version is 0.14.0
- Additional documentation here
- .Net version is 1.11.0
- PHP version is 2.10.0
- Python version is 2.8.0
Below are the main API change call-outs for the Credit Invoices feature:
Starting in API v2.10, all API 201 responses that previously returned the invoice object will now return an invoice_collection with a charge_invoice and an array of credit_invoices. Without Credit Invoices enabled, this response will only return an invoice in the charge_invoice block. Once the Credit Invoices feature is enabled, it is possible to get an invoice_collection response with only a charge invoice, only a credit invoice, multiple credit invoices, or a charge invoice and one or many credit invoices.
For example, an immediate subscription change from a Silver plan to a Gold plan will return a charge invoice for the Gold fees and a credit invoice for the Silver refund. Multiple credit invoices are possible when the upgrade included a custom credit, for example a promotional credit, which will be issued on a separate origin "credit" credit invoice.
Once the Credit invoices feature is enabled, the invoice object will return the following attributes and support the following actions.
The total_in_cents minus all successful transactions and credit payments for the invoice.
Whether the invoice is a "credit" invoice or "charge" invoice. All invoices created before the Credit Invoices feature was enabled on the site will have type of "legacy".
This is a query attribute.
New values and renamed values
The state of the invoice. This is a query attribute.
If type = charge or legacy: pending (used to be 'open'), processing, past_due, paid (used to be 'collected'), failed
If type = credit: open, processing, closed, voided
The event that created the invoice.
If type = charge: purchase, renewal, immediate_change, termination
If type = credit: immediate_change, refund, credit, termination, gift_card, write_off, external_credit
If type = legacy: purchase, refund
Rename of "original_invoice" and changed to be a resource to a new list endpoint
If the invoice type is credit, this is the list of original invoices the credit adjustments on the credit invoice are against.
New resource to a new list endpoint
If the invoice type is charge, this is the list of credit invoices with credit adjustments against the charge adjustments on this invoice.
Lists the credit payments associated with the invoice. Note that not all credit payments affect the invoice balance. It is important to look at the "action" of the credit payment.
Note that if the invoice type is "credit", the following invoice attributes will always be nil:
POST /v2/accounts/<account_code>/invoices and /preview
- Now returns the invoice_collection
- Now supports "type" in the request to only invoice charges or credits
- If only uninvoiced credits on the account, only credit_customer_notes can be specified and will set customer notes on the credit invoice.
- If a mix of uninvoiced charges and credits are on the account, specifying credit_customer_notes will set customer notes on the credit invoice.
- 400 - No Adjustments
- 400 - No Charge Adjustments
- 400 - No Credit Adjustments
- 400 - Must Be Blank For Type
- 400 - Feature Not Enabled
<error> <symbol>will_not_invoice</symbol> <description>No adjustments to invoice</description> </error>
<error> <symbol>will_not_invoice</symbol> <description>No charge adjustments to invoice</description> </error>
<error> <symbol>will_not_invoice</symbol> <description>No credit adjustments to invoice</description> </error>
<errors> <error field="invoice.terms_and_conditions" symbol="present">must be blank</error> </errors>
<error> <symbol>feature_not_enabled</symbol> <description>credit_customer_notes allowed only if Credit Memos feature is enabled and API version is 2.10 or greater</description> </error>
New endpoint that lists the original charge invoices the credit invoice is against.
<error> <symbol>invoice_type_invalid</symbol> <description>Invoice type must be `credit` to view original_invoices</description> </error>
New endpoint that lists the credit invoices issued against the charge invoice.
<error> <symbol>invoice_type_invalid</symbol> <description>Invoice type must be `charge` to view credit_invoices</description> </error>
New endpoint to void a credit invoice with an open balance. If the balance is partially used, the invoice will move to a closed state instead of a voided state. In both cases, the balance is removed through the creation of a credit payment with action of "reduction".
<error> <symbol>unable_to_void</symbol> <description>Invoice type is not voidable</description> </error>
<error> <symbol>unable_to_void</symbol> <description>No balance remaining</description> </error>
The mark_failed endpoint will now return the invoice_collection array with the charge invoice that was failed and now a write-off credit invoice. Note that failing a legacy invoice after the Credit Invoices feature is enabled will not credit a write-off credit invoice, so a credit invoice will not be returned in the response.
The refund endpoint now supports two concepts. If the invoice being refunded is a legacy or charge invoice, the endpoint will issue a refund credit invoice. This is what you would normally think of as a refund today. If the invoice being refunded is a credit invoice, the balance of the credit invoice will be refunded as transactions. This is a new concept where a refund issued as credit can later have the balance refunded out as transactions.
Here are the new refund request attributes on the invoice object:
Once Credit Invoices is enabled, the default of refund_method switches to transaction_first, instead of the previous credit_first.
These are two new additional refund method.
all_credit will issue the refund credit invoice with a full credit balance.
all_transaction will attempt to refund as much of the credit balance to transactions where possible. For example, it will attempt to refund a credit payment on the original invoice as a transaction.
When refunding the balance of an already issued credit invoice, refund_method must be all_transaction.
True if the refund transactions should be external (manually entered) transactions.
Defaults to false.
If refunding a manual collection invoice, external_refund must be set to true.
check, credit card
The payment method of the external refund transactions.
If external_refund is true, payment_method is required.
The date of the external refund transactions. Stored in the collected_at on the transactions created. Defaults to timenow.
Only allowed if external_refund is true.
If refunding a charge or legacy invoice, this is the amount of the "open amount" refund. If refunding the balance of a credit invoice, this is the amount of the external refund. Defaults to the full refundable balance.
If the invoice is a credit invoice, only allowed if external_refund is true.
Partial refund to wire transfer.
An optional note for the external refund transactions created.
Only allowed if external_refund is true.
This refund is for the service issues reported. Thanks for your loyalty!
An optional note to the customer to show on the refund credit invoice.
Only allowed if refunding a legacy or charge invoice, since once a refund credit invoice is issued, the notes cannot be edited.
- 400 - Must Specify External Refund
- 422 - Refund Amount Too Large
- 400 - Refund Quantity Too Large
- 400 - Only One Refund Type
- 400 - No Refundable Balance
- 400 - Must Specify All Transaction
- 400 - Must Specify Payment Method
<error> <symbol>external_refund_invalid</symbol> <description>external_refund must be true for manual collecting invoices</description> </error>
<errors> <error field="invoice.invoice" symbol="less_than_refund_amount">amount available for refund cannot be less than the amount to be refunded</error> </errors>
<errors> <error field="invoice.charges" symbol="">Quantity only has 1 item left</error> </errors>
<error> <symbol>only_one_refund_type</symbol> <description>You cannot specify both an amount and line items to refund</description> </error>
<error> <symbol>unable_to_refund</symbol> <description> <error> <symbol>refund_method_invalid</symbol> <description>Invalid refund_method (must be all_transaction)</description> </error>Only refund invoices with a refundable balance can be refunded.</description> </error>
<error> <symbol>refund_method_invalid</symbol> <description>Invalid refund_method (must be all_transaction)</description> </error>
<error> <symbol>payment_method_invalid</symbol> <description>Invalid payment_method (must be one of credit_card, paypal, amazon, roku, ach, apple_pay, sepadirectdebit, eft, wire_transfer, money_order, check, other)</description> </error>
Once the Credit invoices feature is enabled, Recurly will no longer create adjustments with origin of "carryforward" or credits that link back to other credits. Remaining credit balances are now represented by the balance_in_cents on the invoice with type of "credit". The individual credit payments that reduced the credit balance are represented in our new credit payment object, which is provided as an array when viewing an invoice.
Additionally, the adjustment object will return the following attributes and support the following actions.
The reason code for the credit. Learn more here.
Changed to a resource
The charge adjustment the credit is against. Previously we only showed an original_adjustment pointing to a previous credit. Now that carryfoward credits are going away, the original_adjustment will only exist for issued credits and will point to the original chard.
New resource to a new list endpoint
If the adjustment is a charge, this resource will link to a list of all credit adjustments where the original_adjustment is this adjustment. Meaning, these are the credits issued against the charge.
The create adjustment endpoint now supports setting a credit_reason_code when creating a credit. The credit_reason_code for a one-off custom credit can be "general", "service", or "promotional".
<errors> <error field="adjustment.credit_reason_code" symbol="present">must be blank</error> </errors>
New endpoint to view the credit adjustments issued against a charge adjustment.
<error> <symbol>adjustment_type_invalid</symbol> <description>Adjustment type must be `charge` to view credit_adjustments</description> </error>
Credit payments are created automatically by Recurly when a credit invoice balance is used as payment on a charge invoice, or when a credit invoice's balance is removed or a credit payment refunded as a transaction. Credit payments cannot be directly created via the API. Credit payments are viewable in an array on the invoice the credit payment is associated with.
Aside from viewing and invoice, these view endpoints exist for credit payments:
Here are the attributes of the credit payment object:
A resource to the account the credit payment is on.
The unique id of the credit payment.
payment, gift_card, write_off, reduction, refund
The action that resulted in the credit payment being created. See action filter table above for details.
The currency of the credit payment amount.
The amount of the credit payment, which will always be positive.
The credit invoice the credit payment came from.
The invoice the credit payment was applied to. If action is payment, gift_card, or write_off, this is a charge invoice. If action is reduction or refund, this is a credit invoice.
The credit payment the refund action credit payment is refunding. Will only populate if the action on the row is "refund".
The refund transaction the refund action credit payment is transferring value to. Will only populate if the action on the row is "refund".
2017-12-02 17:58:09 UTC
The date and time the credit payment was created.
2017-12-02 17:58:09 UTC
The date and time the credit payment was updated, which would be when it was created or voided.
2017-12-02 17:58:09 UTC
The date and time the credit payment was voided due to the applied invoice being failed.
The Partner API has been updated for the Credit Invoices changes. Please see our Change Log versions 2017-09-30 and 2018-01-24 for more details.
There are three important updates to webhooks:
Charge invoices will send a new set of charge_invoice notifications, and credit invoices will send a new set of credit_invoice notifications. Legacy invoices will continue to send the current invoice notifications. Note that shipping address will only show if one exists for the invoice.
The new_dunning_event notification will have a new invoice block once the Credit Invoices feature is enabled on the Recurly site. Note that shipping address will only show if one exists for the invoice.
Credit payments come with a new set of credit_payment notifications.
To enable the Credit Invoices feature on your Recurly site, go to Configuration > Invoice Settings and click "Enable" under Credit Invoices. Please review this documentation page and update your integration and internal processes before enabling the feature. Due to the number of changes with this feature, we advise all merchants to test the feature on a sandbox site before going live in production.