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    

Credit Invoices Release

This page details all new functionality and updates included in the new Credit Invoices feature. Please review all documentation before enabling the feature on your Recurly site.

Before you enable Credit Invoices

  • Your Recurly site must have the Only Bill What Changed feature enabled in order to enable Credit Invoices.
  • 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 enabled.

Feature Overview

Recurly now supports the issuing of credit memos / credit notes through our Credit Invoices feature.

Go Live with Credit Invoices Checklist

Before you enable the Credit Invoices feature on your production Recurly site, please confirm you have taken the following steps:

What is a credit invoice?

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 its own invoice. Separating issued credits from issued charges provides clean gross numbers for your finance team, supports 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:

Credit

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.

Refund

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.

Write-Off

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 write-off credit invoice.

The failed charge invoice.

The failed charge invoice.

What is a credit payment?

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.

A charge invoice paid with a $20 credit payment and $30 credit card transaction.

Credit Payment Actions

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.

Action
Description

Payment

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.

Gift Card

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.

Write-Off

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.

Reduction

The reduction action is used to remove a credit balance from a credit invoice.

Refund

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.

How Existing Carryforward Credits Transfer

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. Once the Credit Invoices feature is enabled, these "carryforward" credits are no longer created, 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 automatically put all uninvoiced carryforward credits on an account onto a new credit invoice as soon as 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. Note that these invoices are not sent to your customers via email, since they represent credits that already existed on customer accounts.

Any uninvoiced credits on the account that have yet to be issued to the customer, and thus are not carryforward credits, must be invoiced via the API or 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, or until the custom credit is invoiced via the API. The credit will not be put on an origin carryforward_credit invoice, and it will not be applied to any charge invoices until it's been invoiced.

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.

New Invoice Origins

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.

Learn about all of the possible invoice origins.

Immediate Downgrades and Upgrades

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.

One-off Credit Invoices

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 via the Recurly Admin Console, go to the customer's 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.

Using this method, it is no longer possible to create an uninvoiced credit adjustment on an account. All one-off credits are issued on an invoice immediately. However, 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.

You can still create uninvoiced credit adjustments on the account through our API. Custom credits created through the Adjustments endpoint will not be invoiced immediately. When the custom credit is created via the Adjustments endpoint, it must be invoiced via the API or it will be invoiced automatically when a subscription is created or renewed. Uninvoiced credits will not be applied to charge invoices until the credits have been invoiced.

New Refund Options

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:

Refund the Remaining Prorated Amount

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.

Refund to Credit Balance

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)

Refund Credit Payment to Original Payment Method

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.

Example:

  1. Subscribe your customer to Gold for $50.
  2. Immediately downgrade your customer to Silver for $40. This will issue a refund credit invoice with an open balance of ($10).
  3. 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.
  4. 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.

Why Does Recurly Create Multiple Refund Transactions?

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.

Options When Refunds Go Wrong

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.

Keep The Refund as a Credit Balance

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.

Retry The Refund Transaction

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.

Record an External Refund Transaction

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.

Void the Credit Invoice

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.

Write-Offs

When a charge invoice is failed directly (e.g. stopping collection of the invoice) 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 identify write-offs at every level.

As soon as the write-off invoice is created, its 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 that was created before the Credit Invoices feature was enabled on the site (i.e. a legacy invoice) 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.

Void a Credit Invoice or Balance

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.

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

New Credit Limits

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.

Reissue Invoice and Then Change Subscription

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.

Extend Subscription Cycle and Then Change Subscription

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.

Taxes and Credit Invoices

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.

Updates to Emails

The Credit Invoices feature comes with a few changes to your email templates:

Payment Confirmation

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.

Payment Refunded

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.

Subscription Change

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

New Credit Invoice

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.

Updates to Exports

Automated Exports

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.

Invoices

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.

Invoices - Summary

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.

Filters Changes

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.

Column Changes

invoice_type

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.

invoice_doc_type

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.

invoice_balance

The invoice_balance is the current balance of the charge or credit invoice. Legacy invoice will never have a balance value.

invoice_balance_modified_at

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

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.

status

The status column previously included values of open, processing, past_due, collected, and failed. This column now shows the updated status values of the invoice, which indicate the state of the invoice. This includes changing open to pending, changing collected to paid, and adding statuses for credit invoices. See a full overview of what each invoice status means.

Adjustments and Adjustments - Coupons

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.

Column Changes

invoice_type

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.

adjustment_credit_reason_code

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

Adjustment Credit Reason Code
Description

general

The default value for a one-off custom credit adjustment.

service

A possible value for a one-off custom credit adjustment. Useful in tracking credits issued due to business issues or customer happiness.

promotional

A possible value for a one-off custom credit adjustment. Useful in tracking credits issued as part of a promotion.

refund

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.

write_off

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.

gift_card

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.

adjustment_refundable_amount

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.

invoice_state

The invoice_state column previously included values of open, processing, past_due, collected, and failed. This column now shows the updated status values of the invoice, which indicate the state of the invoice. This includes changing open to pending, changing collected to paid, and adding statuses for credit invoices. See a full overview of what each invoice status means.

Credit Payments

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.

Learn about our new Credit Payments export.

Accounts Receivable

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.

Columns

invoice_balance

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.

invoice_balance_modified_at

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.

Revenue Recognition Schedules

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.

Filter Changes

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.

Column Changes

invoice_origin

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.

Updates to the API and SDKs

All API updates for the Credit Invoices feature are on version 2.10 and above. We recommend updating to the latest version of the API so that you have the most up-to-date functionality..

Below are the main API change call-outs for the Credit Invoices feature:

invoice_collection

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.

Updates to the Invoice Object

Once the Credit invoices feature is enabled, the invoice object will return the following attributes and support the following actions.

Invoice Attribute Changes

Attribute
Change
Description

balance_in_cents

New attribute

The total_in_cents minus all successful transactions and credit payments for the invoice.

type

New attribute

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.

state

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

origin

New attribute

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, usage_correction (for usage-based billing only), carryforward_credit, and carryforward_gift_credit (for one-time, migration related credits)

If type = legacy: purchase, refund

Learn more about the invoice origin.

original_invoices

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.
This element is not returned if the invoice type is charge.

credit_invoices

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.
This element is not returned if the invoice type is credit.

credit_payments

New array

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:

  • collection_method
  • po_number
  • net_terms
  • terms_and_conditions
  • vat_reverse_charge_notes
  • attempt_next_collection_at
  • recovery_reason

Invoice Action Changes

Post Invoice

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.
Errors
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>will_not_invoice</symbol>
    <description>No adjustments to invoice</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>will_not_invoice</symbol>
    <description>No charge adjustments to invoice</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>will_not_invoice</symbol>
    <description>No credit adjustments to invoice</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error field="invoice.terms_and_conditions" symbol="present">must be blank</error>
</errors>
<?xml version="1.0" encoding="UTF-8"?>
<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>
View Original Invoices

New endpoint that lists the original charge invoices the credit invoice is against.

GET /v2/invoices/<invoice_number>/original_invoices

Errors
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>invoice_type_invalid</symbol>
    <description>Invoice type must be `credit` to view original_invoices</description>
</error>
View Credit Invoices

New endpoint that lists the credit invoices issued against the charge invoice.

GET /v2/invoices/<invoice_number>/credit_invoices

Errors
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>invoice_type_invalid</symbol>
    <description>Invoice type must be `charge` to view credit_invoices</description>
</error>
Void Credit Invoice

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

PUT /v2/invoices/<invoice_number>/void

Errors
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>unable_to_void</symbol>
    <description>Invoice type is not voidable</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>unable_to_void</symbol>
    <description>No balance remaining</description>
</error>
Mark Failed

The mark_failed endpoint will now return the invoice_collection array with the charge invoice that was failed as well as 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.

PUT /v2/invoices/<invoice_number>/mark_failed

Refund Invoice

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:

Request Attribute
Example
Description

refund_method

all_credit, all_transaction

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.

external_refund

true, false

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.

payment_method

check, credit card

The payment method of the external refund transactions.

If external_refund is true, payment_method is required.

refunded_at

2018-02-13T00:44:35Z

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.

amount_in_cents

500

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.

description

Partial refund to wire transfer.

An optional note for the external refund transactions created.

Only allowed if external_refund is true.

credit_customer_notes

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.

Errors
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>external_refund_invalid</symbol>
    <description>external_refund must be true for manual collecting invoices</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<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>
<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error field="invoice.charges" symbol="">Quantity only has 1 item left</error>
</errors>
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>only_one_refund_type</symbol>
    <description>You cannot specify both an amount and line items to refund</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>unable_to_refund</symbol>
    <description><?xml version="1.0" encoding="UTF-8"?>
<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>
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>refund_method_invalid</symbol>
    <description>Invalid refund_method (must be all_transaction)</description>
</error>
<?xml version="1.0" encoding="UTF-8"?>
<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>

Updates to the Adjustment Object

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.

Adjustment Attribute Changes

Attribute
Change
Description

credit_reason_code

New attribute

The reason code for the credit. Learn more here.

original_adjustment

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.

credit_adjustments

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.

Adjustment Action Changes

Create Credit

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

POST /v2/accounts/<account_code>/adjustments

Errors
<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error field="adjustment.credit_reason_code" symbol="present">must be blank</error>
</errors>
View Credit Adjustments

New endpoint to view the credit adjustments issued against a charge adjustment.

GET /v2/adjustments/<uuid>/credit_adjustments

Errors
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <symbol>adjustment_type_invalid</symbol>
    <description>Adjustment type must be `charge` to view credit_adjustments</description>
</error>

New Credit Payment Object

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:

GET /v2/credit_payments
GET /v2/credit_payments/<uuid>
GET /v2/adjustments/<uuid>/credit_adjustments
GET /v2/accounts/<account_code>/credit_payments

Here are the attributes of the credit payment object:

Attribute
Example
Description

account

Resource link

A resource to the account the credit payment is on.

uuid

41872c1bf4bcfcd5658d86401194f63b

The unique id of the credit payment.

action

payment, gift_card, write_off, reduction, refund

The action that resulted in the credit payment being created. See action filter table above for details.

Learn more about the credit payment action.

currency

USD

The currency of the credit payment amount.

amount_in_cents

500

The amount of the credit payment, which will always be positive.

original_invoice

Resource link

The credit invoice the credit payment came from.

applied_to_invoice

Resource link

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.

original_credit_payment

Resource link

The credit payment the refund action credit payment is refunding. Will only populate if the action on the row is "refund".

refund_transaction

Resource link

The refund transaction the refund action credit payment is transferring value to. Will only populate if the action on the row is "refund".

created_at

2017-12-02 17:58:09 UTC

The date and time the credit payment was created.

updated_at

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.

voided_at

2017-12-02 17:58:09 UTC

The date and time the credit payment was voided due to the applied invoice being failed.

Updates to the Partner API

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.

Updates to Webhooks

There are three important updates to webhooks:

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

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

  3. Credit payments come with a new set of credit_payment notifications.

Enable the Credit Invoices Feature

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.

Credit Invoices Release


This page details all new functionality and updates included in the new Credit Invoices feature. Please review all documentation before enabling the feature on your Recurly site.

Suggested Edits are limited on API Reference Pages

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