{"__v":14,"_id":"565f2e2423fd5f0d00a12a93","category":{"__v":11,"_id":"565def2677f0090d005819bb","pages":["565def2bb311ea0d00a38597","565f2d5d413e06170093dea4","565f2d840dc99e1900f24bb8","565f2dd8bca87d0d006bc68a","565f2e2423fd5f0d00a12a93","565f2f7c0dc99e1900f24bc2","565f2fadbca87d0d006bc698","565f2fe223fd5f0d00a12a9b","565f3011413e06170093debe","565f3040ea46251700972769","5665df7bd8a06b170063f30b"],"project":"56450a342229d7170010928a","version":"56450a342229d7170010928d","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-01T19:04:06.860Z","from_sync":false,"order":1,"slug":"reference","title":"Reference"},"parentDoc":null,"project":"56450a342229d7170010928a","user":"55648cf93b87582b003ab8b1","version":{"__v":9,"_id":"56450a342229d7170010928d","project":"56450a342229d7170010928a","createdAt":"2015-11-12T21:52:52.685Z","releaseDate":"2015-11-12T21:52:52.684Z","categories":["56450a352229d7170010928e","56450a472c74cf1900da48ca","565def2677f0090d005819bb","5665dfa0e93ae70d00b96a2a","5665e3db1b6559190020ae8c","5665e47763109d0d0036ba5a","5690123f18c3920d00be8b1c","56944016d8c04d1700e5ae20","569447891005590d0062cace"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["56f190283af4942b00bb3c5f"],"createdAt":"2015-12-02T17:45:08.813Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"## Dashboard\n\n[Your invoices dashboard][1] provides an overview of all invoices generated by Recurly. The filters on this view allow you to bucket invoices into different categories for easy sorting:\n\n[1]: https://app.recurly.com/go/invoices\n\n####All\nEvery invoice generated within your Recurly site.\n####Pending\nAll manual invoices that have not yet reached the end date of their collection terms.\n####Past Due\nAll invoices that attempted collection, but payment failed. These invoices will be retried automatically through <a href='/docs/dunning-management'>the dunning process</a>.\n####Failed\nAll invoices that have either experienced 20 declines, or has been through the dunning process without successful payment. These invoices will not be retried.\n####Closed\nAll successfully collected invoices.\n\n## Invoice Search\n\nYou may search for an invoice on any of the following fields:\n\n* Account code\n* Company name\n* First name\n* Last name\n* Email address\n* Username\n* Address\n* Amount\n* Invoice number\n* PO number\n\n## Structure\n\nBy default, your invoices will contain the following information:\n\n####Company Details\nCompany information configured in your [site settings](https://app.recurly.com/go/configuration/edit).\n####Customer Details\nThe account holder's name and address information.\n####Line Items\nInvoice line items contain any subscription or add-on description, as well as quantities and descriptions for charges and credits applied to the invoice. For recurring charges, the line items will include the bill cycle covered by this renewal charge. If a discount is applied, then the amount discounted from any active <a href='/docs/coupons'>coupons</a> are identified by line item.\n####Subtotal\nSubtotal of the line item amounts, after charges and credits are applied.\n####Taxes\nTotal of the applicable taxes (as denoted by an asterisk in the line item rows). Customer must have a postal code and country for tax to be calculated. The customer address is taken from Billing Info for automatic invoices (e.g. - credit card, PayPal) and Account Info for manual invoices. See the full list of supported tax regions <a href=\"https://docs.recurly.com/tax\">here</a>.\n####Total\nInvoice total, after taxes and coupons.\n####Amount Paid\nFor refund invoices, the Amount Paid is not displayed.\n####Amount Due/Refund Amount\nAmount currently due for the invoice. For refund invoices, the total refunded amount back to the customer\n####Credit to Account\nThe remaining credit applied back to the customer’s account from the current invoice.\n\n## Customer Details\n\nThe customer's information on the invoice can include First and Last Name, Company, VAT Number, and Address. Company will always come from the Account Information. All other details will come from either the Account Information or the Billing Information depending on the invoice collection method and your site's Tax Settings.  \n\n** Automatic Collection **\nIf the invoice collection method is automatic, the customer details will default to the Billing Information. If you want to always use the Account Information address, you can select \"Use Account Information Address for all Invoices\" under Configuration > Taxes > Tax Settings. If enabled, this option will use the Account Information on all automatic collection invoices. If the Account Information is missing an address, it will default to the Billing Information address.\n\n** Manual Collection **\nIf the invoice collection method is manual, the customer details will always use the Account Information. If the Account Information is empty and Billing Information exists, the invoice will ignore the Billing Information and will show blank customer details on the invoice.\n\n## Customization\n\nInvoices will soon have two new notes sections. These notes will only show up on invoices if there is text in those sections. Notes can be configured to have site level defaults for all invoices, as well as be customized for specific invoices through the Admin or API. Site level defaults can be configured on the  [Invoice Settings](https://app.recurly.com/go/configuration/invoice_settings/edit) page. Invoice specific notes are made when generating an invoice or creating/editing a subscription.\n\n####Terms and Conditions\nAn extra notes section for payment terms, payment details, legal notes, or whatever you like! The title of this notes section cannot be changed.\n####Customer Notes\nAn extra notes section for customer notes. This could be special details about the invoice, a note to say \"thanks for your business\", or whatever you like! The title of this notes section will not show on the invoice.\n\n## Proration\n\nA subscription change with a timeframe of immediately will generate an invoice that displays additional line items that includes prorated tax amounts:\n\n####Prorating for remainder of subscription term\nCharges from upgrading.\n####Remaining value for the subscription\nCredit due to downgrade.\n\n## Collection\n\n### Automatic\n\nSubscription signups and [one-time transactions][2] are invoiced and collected upon immediately. Subscription renewals and manual charges are invoiced and then processed at the top of every hour.\n\n[2]: /docs/transactions\n\n### Manual\n\nAn **Open** invoice can be manually marked as **Closed** by opening the invoice in your admin console and clicking the **Stop Collection** tab. This will give you two options:\n\n**Stop Collecting**\nIndicates that the invoice was not successfully paid for and that collection attempts should stop. This functionality is mostly used to halt the dunning procedures for an invoice.\n\n**Mark Paid**\nIndicates that the invoice was successfully paid for and that automated collection attempts should stop - this functionality is typically used to indicate that payment was received via another method and that revenue should be recognized.\n\n\n## Dunning\n\nWhen invoice collection fails, the invoice immediately enters a **Past Due** state and collection attempts will start based on [your dunning management settings][3]. Recurly will email the customer to alert them of the failed payment and automatically retry payment based on the card and error type. Reviewing the invoice details will display each collection attempt and reason for the payment decline. Recurly will stop trying to collect on an invoice after it has been attempted 20 times, or when the timeline in [your dunning management settings][3] has passed without successful collection.\n\n[3]: https://app.recurly.com/go/configuration/dunning\n\nPlease Note: Stopping collection on an invoice *will not* automatically cancel the related subscription. The subscription needs to be canceled separately in order to stop the subscription from renewing again.\n\n## Invoice Numbers\n\nAll invoice start with number `1000` and increment by 1 with each invoice creation. If you need your invoices to start at a specific value, please [contact Recurly support][4].\n\n[4]: /docs/contact\n\n## Sandbox Invoices\n\nInvoices created while in sandbox will include a \"TEST INVOICE\" watermark. The watermark is only relevant to sandbox invoices -- after moving to production, production invoices will not include the watermark.\n\n## Emails\n\nWhen a customer subscribes, their first invoice is automatically included in the New Subscription email template. Subsequent invoices are sent using the Payment Confirmation email template. Recurring invoices are not sent to customers when the total amount owed is $0.00. An invoice email can be resent by clicking the **Resend Last Email** button on a specific invoice. You can attach a PDF of the invoice to all of your invoice related emails by enabling this feature on the [Invoice Settings](https://app.recurly.com/go/configuration/invoice_settings/edit) page.\n\n## PDFs\n\nPDF invoices are available to merchants and customers through multiple venues.\n\n* Admin Invoices Overview and Invoice Details pages\n* API\n* Hosted Account Management Invoices table and Invoice Details pages\n* Invoice related Email Templates\n\nPDF invoices are not customizable at this time.\n\n## Invoices for Refunds and Voids\n\nRecurly creates a new invoice for any refund or voided transactions, instead of reopening the original invoice. The second invoice makes it clear to your finance team that the previously collected amount has now been reversed. Transactions can be only be voided in a short period of time after the original successful transaction, but it is possible that the void can happen after your reporting period has closed, so the second invoice will make sure you see the change.\n\nThere are two ways to refund or void, [line item refunds](https://dev.recurly.com/docs/line-item-refunds) or [open amount refunds](https://dev.recurly.com/docs/open-amount-refunds). We recommend that you use line item refunds because the original line item identity is carried over to the refund invoice. Open amount refunds create custom refund amounts on an invoice level, so all line item identity is lost and a new general credit is created on the resulting invoice.\n\nInvoices for refunds and voids have a type of \"refund\", where as the original invoice will have a type of \"purchase\". All successful refund invoices will have a state of \"paid\".\n\n### How to Refund or Void\n\nTo create a refund or void a transaction, you can either select the original purchase invoice or the successful transaction. If you are on the invoice page, you will see the option to refund in the sidebar. If you are on the transaction details page, you will see a button to refund the transaction in the top right corner of the page. Both methods will take you to the same refund page.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/zilOUy3R0ag59mlEwwtg_ini-refund.png\",\n        \"ini-refund.png\",\n        \"600\",\n        \"641\",\n        \"#8a5c9e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Refundable Amount and Credits\n\nRefunds defined by invoice line items provide greater accuracy in accounting and taxes. When you consider an invoice with charge and credit line items, the <strong>full value of the invoice is the sum of the charges</strong>. Therefore, the total refundable amount of an invoice is the total of all the charges, not the transaction amount.\n\nWhen credit line items exist on an invoice, a partial refund could refund credit back to the account first or a transaction giving money back to the customer first. Recurly defaults to \"credit first\" to favor the merchant.\n\n** Example **\nAn invoice has a $10.00 charge and a -$5.00 credit. The total and transaction for the invoice was $5.00. The total value of the original invoice is $10.00, so a full refund amount would be $10.00.\n\nIf you want to refund $4.00, you have the option of refunding credit to the account or a transaction giving money back to the customer.\n\n* Credit first will result in a $4.00 credit on the account, no money back to the customer.\n* Transaction first will result in a $4.00 transaction returning money back to the customer.\n\nIf you refund $6.00:\n\n* You could choose credit first and put a $5.00 credit on the account and a $1.00 transaction back to the customer.\n* Or you could choose transaction first and give $5.00 of money back to the customer and $1.00 of credit on the account.\n\n### Line item refunds\n\nLine item refunds allows you to select the specific line items to refund from the invoice, including the quantity and whether or not you want to prorate the amount based on the current period (<i>Note: unless the 'prorate' option is selected, the full amount will be refunded by default</i>). We handle the calculations for any discount or tax if applicable for the refund, which you can verify on the preview page before confirming the refund. The feature is available in your Admin Panel and also via <a href=\"https://dev.recurly.com/docs/line-item-refunds\">API</a>.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c5ZDzSInRU6a4C5zYIhw_select-line.png\",\n        \"select-line.png\",\n        \"600\",\n        \"360\",\n        \"#9d5ab7\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nOnce you confirm and the refund is successful, we create a refund invoice so that you can pass along to your customer or store internally for your own records.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ivN1YopXTlyElkqgENuO_refund-inv.png\",\n        \"refund-inv.png\",\n        \"600\",\n        \"713\",\n        \"#922aa7\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Open amount refunds\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Open amount refunds do not maintain line item identity\",\n  \"body\": \"We recommend using Line Item Refunds when you can because Open Amount Refunds refund at the invoice level.\\n* This means the resulting refund line item has no subscription, product or accounting code identity.\\n* Due to this, open amount refunds with tax will back out the tax, which can cause rounding issues since this method is the reverse of how the purchase invoice calculates tax on top of the subtotal.\"\n}\n[/block]\nOpen amount refunds allows you to specify the amount you’d like to refund irrespective of a particular line item. This may be case when you need to refund a partial amount of a line time that isn’t tied to the prorated amount, or simply a partial refund for a random amount due to special circumstances. Either way, Recurly let’s you set the custom amount for the refund as along as it does not exceed the amount of the transaction, or the amount remaining that’s available to refund. The feature is available in your Admin Panel and also via <a href=\"https://dev.recurly.com/docs/open-amount-refunds\">API</a>.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4j2Wo4w9SGgSMsFYcxBQ_open-refund.png\",\n        \"open-refund.png\",\n        \"600\",\n        \"282\",\n        \"#4c6d8d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAlso for open amount refunds, we calculate in the tax if it was applied on the original invoice for you as part of the amount that you specify. Once the open amount is is confirmed, we provide you with the refund invoice that references the original invoice number, which you pass to your customer or store for your own internal records.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/RgSkxZaiRca1wuApr0uL_open-inv.png\",\n        \"open-inv.png\",\n        \"600\",\n        \"714\",\n        \"#6097be\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Terminating and Refunding Subscriptions\n\nSimilar to a line item or open amount refund, when a subscription is terminated and refunded a refund invoice will be created for the appropriate amount.\n\nWhen terminating and refunding, Recurly refunds the most recent invoice associated with that subscription UUID. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will create a refund invoice and apply the credit back to the customer's account.\n\n### Voids\n\nIf a paid invoice has a transaction that has not settled yet, a refund will trigger a void. The transaction will be voided and a new refund invoice will be generated. The new invoice will be a negative invoice with a state of \"paid\" and an invoice type of \"refund\", but the invoice itself will display \"VOIDED\" in purple with a footnote of \"Refund of invoice #1001 due to voided transaction\". Note that the original invoice will still be a positive invoice with a state of \"paid\" and an invoice type of \"purchase\".\n\nYou will need to do a full refund when attempting to void. A prorated void will display an error. You can only void the full amount of the original invoice because the associated transaction has not settled.\n\n### Webhooks\nRefunds and voids will now have three webhooks. The first is the normal successful_refund or void_payment transaction webhooks. These will be accompanied by two webhooks for the associated invoice: new_invoice, closed_invoice.\n\n### Payment History\nWhen viewing invoices in the admin console, each invoice will include a \"Payment History\" section that references all transactions and other invoices that are related to the invoice. For example, if an invoice is successfully paid then later refunded, the Payment History for that invoice will link to the original transaction, as well as the related refund invoice.\n\nThe Payment History is only available when viewing an invoice in the Recurly admin console. This is strictly an internal tool to help merchants tie related transactions/invoices together, and will not be displayed on customer-facing invoices.\n\n### Subscription Changes\nRecurly does not reconcile invoice payments with subscription requests. If a subscription has a refund in the current billing cycle, updates with an effective date of \"Immediately\" will always credit the customer as if the refund never existed. Updates with an effective date of \"On next renewal\" will not have this problem.\n* If you issue a refund and then need to change the subscription in the same billing cycle, Recurly recommends you make the change \"On next renewal\".\n* If you make a subscription change and then need to issue a refund in the same billing cycle, Recurly recommends only refunding the subscription change invoice since the previous invoice was already been refunded through any credit applied to the subscription change invoice.","excerpt":"An invoice relates charges, credits, and payments together. When a subscription is created or renewed, or a charge is created on the account, Recurly will sum the charges, discount or tax as appropriate, and send the invoice out for collection. Your subscribers are notified of successful or failed invoice collection via email.","slug":"invoices","type":"basic","title":"Invoices"}

Invoices

An invoice relates charges, credits, and payments together. When a subscription is created or renewed, or a charge is created on the account, Recurly will sum the charges, discount or tax as appropriate, and send the invoice out for collection. Your subscribers are notified of successful or failed invoice collection via email.

## Dashboard [Your invoices dashboard][1] provides an overview of all invoices generated by Recurly. The filters on this view allow you to bucket invoices into different categories for easy sorting: [1]: https://app.recurly.com/go/invoices ####All Every invoice generated within your Recurly site. ####Pending All manual invoices that have not yet reached the end date of their collection terms. ####Past Due All invoices that attempted collection, but payment failed. These invoices will be retried automatically through <a href='/docs/dunning-management'>the dunning process</a>. ####Failed All invoices that have either experienced 20 declines, or has been through the dunning process without successful payment. These invoices will not be retried. ####Closed All successfully collected invoices. ## Invoice Search You may search for an invoice on any of the following fields: * Account code * Company name * First name * Last name * Email address * Username * Address * Amount * Invoice number * PO number ## Structure By default, your invoices will contain the following information: ####Company Details Company information configured in your [site settings](https://app.recurly.com/go/configuration/edit). ####Customer Details The account holder's name and address information. ####Line Items Invoice line items contain any subscription or add-on description, as well as quantities and descriptions for charges and credits applied to the invoice. For recurring charges, the line items will include the bill cycle covered by this renewal charge. If a discount is applied, then the amount discounted from any active <a href='/docs/coupons'>coupons</a> are identified by line item. ####Subtotal Subtotal of the line item amounts, after charges and credits are applied. ####Taxes Total of the applicable taxes (as denoted by an asterisk in the line item rows). Customer must have a postal code and country for tax to be calculated. The customer address is taken from Billing Info for automatic invoices (e.g. - credit card, PayPal) and Account Info for manual invoices. See the full list of supported tax regions <a href="https://docs.recurly.com/tax">here</a>. ####Total Invoice total, after taxes and coupons. ####Amount Paid For refund invoices, the Amount Paid is not displayed. ####Amount Due/Refund Amount Amount currently due for the invoice. For refund invoices, the total refunded amount back to the customer ####Credit to Account The remaining credit applied back to the customer’s account from the current invoice. ## Customer Details The customer's information on the invoice can include First and Last Name, Company, VAT Number, and Address. Company will always come from the Account Information. All other details will come from either the Account Information or the Billing Information depending on the invoice collection method and your site's Tax Settings. ** Automatic Collection ** If the invoice collection method is automatic, the customer details will default to the Billing Information. If you want to always use the Account Information address, you can select "Use Account Information Address for all Invoices" under Configuration > Taxes > Tax Settings. If enabled, this option will use the Account Information on all automatic collection invoices. If the Account Information is missing an address, it will default to the Billing Information address. ** Manual Collection ** If the invoice collection method is manual, the customer details will always use the Account Information. If the Account Information is empty and Billing Information exists, the invoice will ignore the Billing Information and will show blank customer details on the invoice. ## Customization Invoices will soon have two new notes sections. These notes will only show up on invoices if there is text in those sections. Notes can be configured to have site level defaults for all invoices, as well as be customized for specific invoices through the Admin or API. Site level defaults can be configured on the [Invoice Settings](https://app.recurly.com/go/configuration/invoice_settings/edit) page. Invoice specific notes are made when generating an invoice or creating/editing a subscription. ####Terms and Conditions An extra notes section for payment terms, payment details, legal notes, or whatever you like! The title of this notes section cannot be changed. ####Customer Notes An extra notes section for customer notes. This could be special details about the invoice, a note to say "thanks for your business", or whatever you like! The title of this notes section will not show on the invoice. ## Proration A subscription change with a timeframe of immediately will generate an invoice that displays additional line items that includes prorated tax amounts: ####Prorating for remainder of subscription term Charges from upgrading. ####Remaining value for the subscription Credit due to downgrade. ## Collection ### Automatic Subscription signups and [one-time transactions][2] are invoiced and collected upon immediately. Subscription renewals and manual charges are invoiced and then processed at the top of every hour. [2]: /docs/transactions ### Manual An **Open** invoice can be manually marked as **Closed** by opening the invoice in your admin console and clicking the **Stop Collection** tab. This will give you two options: **Stop Collecting** Indicates that the invoice was not successfully paid for and that collection attempts should stop. This functionality is mostly used to halt the dunning procedures for an invoice. **Mark Paid** Indicates that the invoice was successfully paid for and that automated collection attempts should stop - this functionality is typically used to indicate that payment was received via another method and that revenue should be recognized. ## Dunning When invoice collection fails, the invoice immediately enters a **Past Due** state and collection attempts will start based on [your dunning management settings][3]. Recurly will email the customer to alert them of the failed payment and automatically retry payment based on the card and error type. Reviewing the invoice details will display each collection attempt and reason for the payment decline. Recurly will stop trying to collect on an invoice after it has been attempted 20 times, or when the timeline in [your dunning management settings][3] has passed without successful collection. [3]: https://app.recurly.com/go/configuration/dunning Please Note: Stopping collection on an invoice *will not* automatically cancel the related subscription. The subscription needs to be canceled separately in order to stop the subscription from renewing again. ## Invoice Numbers All invoice start with number `1000` and increment by 1 with each invoice creation. If you need your invoices to start at a specific value, please [contact Recurly support][4]. [4]: /docs/contact ## Sandbox Invoices Invoices created while in sandbox will include a "TEST INVOICE" watermark. The watermark is only relevant to sandbox invoices -- after moving to production, production invoices will not include the watermark. ## Emails When a customer subscribes, their first invoice is automatically included in the New Subscription email template. Subsequent invoices are sent using the Payment Confirmation email template. Recurring invoices are not sent to customers when the total amount owed is $0.00. An invoice email can be resent by clicking the **Resend Last Email** button on a specific invoice. You can attach a PDF of the invoice to all of your invoice related emails by enabling this feature on the [Invoice Settings](https://app.recurly.com/go/configuration/invoice_settings/edit) page. ## PDFs PDF invoices are available to merchants and customers through multiple venues. * Admin Invoices Overview and Invoice Details pages * API * Hosted Account Management Invoices table and Invoice Details pages * Invoice related Email Templates PDF invoices are not customizable at this time. ## Invoices for Refunds and Voids Recurly creates a new invoice for any refund or voided transactions, instead of reopening the original invoice. The second invoice makes it clear to your finance team that the previously collected amount has now been reversed. Transactions can be only be voided in a short period of time after the original successful transaction, but it is possible that the void can happen after your reporting period has closed, so the second invoice will make sure you see the change. There are two ways to refund or void, [line item refunds](https://dev.recurly.com/docs/line-item-refunds) or [open amount refunds](https://dev.recurly.com/docs/open-amount-refunds). We recommend that you use line item refunds because the original line item identity is carried over to the refund invoice. Open amount refunds create custom refund amounts on an invoice level, so all line item identity is lost and a new general credit is created on the resulting invoice. Invoices for refunds and voids have a type of "refund", where as the original invoice will have a type of "purchase". All successful refund invoices will have a state of "paid". ### How to Refund or Void To create a refund or void a transaction, you can either select the original purchase invoice or the successful transaction. If you are on the invoice page, you will see the option to refund in the sidebar. If you are on the transaction details page, you will see a button to refund the transaction in the top right corner of the page. Both methods will take you to the same refund page. [block:image] { "images": [ { "image": [ "https://files.readme.io/zilOUy3R0ag59mlEwwtg_ini-refund.png", "ini-refund.png", "600", "641", "#8a5c9e", "" ] } ] } [/block] ### Refundable Amount and Credits Refunds defined by invoice line items provide greater accuracy in accounting and taxes. When you consider an invoice with charge and credit line items, the <strong>full value of the invoice is the sum of the charges</strong>. Therefore, the total refundable amount of an invoice is the total of all the charges, not the transaction amount. When credit line items exist on an invoice, a partial refund could refund credit back to the account first or a transaction giving money back to the customer first. Recurly defaults to "credit first" to favor the merchant. ** Example ** An invoice has a $10.00 charge and a -$5.00 credit. The total and transaction for the invoice was $5.00. The total value of the original invoice is $10.00, so a full refund amount would be $10.00. If you want to refund $4.00, you have the option of refunding credit to the account or a transaction giving money back to the customer. * Credit first will result in a $4.00 credit on the account, no money back to the customer. * Transaction first will result in a $4.00 transaction returning money back to the customer. If you refund $6.00: * You could choose credit first and put a $5.00 credit on the account and a $1.00 transaction back to the customer. * Or you could choose transaction first and give $5.00 of money back to the customer and $1.00 of credit on the account. ### Line item refunds Line item refunds allows you to select the specific line items to refund from the invoice, including the quantity and whether or not you want to prorate the amount based on the current period (<i>Note: unless the 'prorate' option is selected, the full amount will be refunded by default</i>). We handle the calculations for any discount or tax if applicable for the refund, which you can verify on the preview page before confirming the refund. The feature is available in your Admin Panel and also via <a href="https://dev.recurly.com/docs/line-item-refunds">API</a>. [block:image] { "images": [ { "image": [ "https://files.readme.io/c5ZDzSInRU6a4C5zYIhw_select-line.png", "select-line.png", "600", "360", "#9d5ab7", "" ] } ] } [/block] Once you confirm and the refund is successful, we create a refund invoice so that you can pass along to your customer or store internally for your own records. [block:image] { "images": [ { "image": [ "https://files.readme.io/ivN1YopXTlyElkqgENuO_refund-inv.png", "refund-inv.png", "600", "713", "#922aa7", "" ] } ] } [/block] ### Open amount refunds [block:callout] { "type": "warning", "title": "Open amount refunds do not maintain line item identity", "body": "We recommend using Line Item Refunds when you can because Open Amount Refunds refund at the invoice level.\n* This means the resulting refund line item has no subscription, product or accounting code identity.\n* Due to this, open amount refunds with tax will back out the tax, which can cause rounding issues since this method is the reverse of how the purchase invoice calculates tax on top of the subtotal." } [/block] Open amount refunds allows you to specify the amount you’d like to refund irrespective of a particular line item. This may be case when you need to refund a partial amount of a line time that isn’t tied to the prorated amount, or simply a partial refund for a random amount due to special circumstances. Either way, Recurly let’s you set the custom amount for the refund as along as it does not exceed the amount of the transaction, or the amount remaining that’s available to refund. The feature is available in your Admin Panel and also via <a href="https://dev.recurly.com/docs/open-amount-refunds">API</a>. [block:image] { "images": [ { "image": [ "https://files.readme.io/4j2Wo4w9SGgSMsFYcxBQ_open-refund.png", "open-refund.png", "600", "282", "#4c6d8d", "" ] } ] } [/block] Also for open amount refunds, we calculate in the tax if it was applied on the original invoice for you as part of the amount that you specify. Once the open amount is is confirmed, we provide you with the refund invoice that references the original invoice number, which you pass to your customer or store for your own internal records. [block:image] { "images": [ { "image": [ "https://files.readme.io/RgSkxZaiRca1wuApr0uL_open-inv.png", "open-inv.png", "600", "714", "#6097be", "" ] } ] } [/block] ### Terminating and Refunding Subscriptions Similar to a line item or open amount refund, when a subscription is terminated and refunded a refund invoice will be created for the appropriate amount. When terminating and refunding, Recurly refunds the most recent invoice associated with that subscription UUID. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will create a refund invoice and apply the credit back to the customer's account. ### Voids If a paid invoice has a transaction that has not settled yet, a refund will trigger a void. The transaction will be voided and a new refund invoice will be generated. The new invoice will be a negative invoice with a state of "paid" and an invoice type of "refund", but the invoice itself will display "VOIDED" in purple with a footnote of "Refund of invoice #1001 due to voided transaction". Note that the original invoice will still be a positive invoice with a state of "paid" and an invoice type of "purchase". You will need to do a full refund when attempting to void. A prorated void will display an error. You can only void the full amount of the original invoice because the associated transaction has not settled. ### Webhooks Refunds and voids will now have three webhooks. The first is the normal successful_refund or void_payment transaction webhooks. These will be accompanied by two webhooks for the associated invoice: new_invoice, closed_invoice. ### Payment History When viewing invoices in the admin console, each invoice will include a "Payment History" section that references all transactions and other invoices that are related to the invoice. For example, if an invoice is successfully paid then later refunded, the Payment History for that invoice will link to the original transaction, as well as the related refund invoice. The Payment History is only available when viewing an invoice in the Recurly admin console. This is strictly an internal tool to help merchants tie related transactions/invoices together, and will not be displayed on customer-facing invoices. ### Subscription Changes Recurly does not reconcile invoice payments with subscription requests. If a subscription has a refund in the current billing cycle, updates with an effective date of "Immediately" will always credit the customer as if the refund never existed. Updates with an effective date of "On next renewal" will not have this problem. * If you issue a refund and then need to change the subscription in the same billing cycle, Recurly recommends you make the change "On next renewal". * If you make a subscription change and then need to issue a refund in the same billing cycle, Recurly recommends only refunding the subscription change invoice since the previous invoice was already been refunded through any credit applied to the subscription change invoice.