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    

Invoices Exports

Recurly provides two exports to help you retrieve data related to invoices: Invoices - Summary and Invoices - Unused Numbers. These exports complement each other to provide details about different subsets of invoice numbers.

Invoices - Summary

The invoice summary export contains the invoice header information and the summary totals for each of your successfully-generated invoices.

Invoice Status Filter

All

Every invoice generated within your Recurly site, regardless of status.

Open

All invoices that have not received a payment attempt. This status has a value of 'pending' in the export and does not include invoices with a 'past_due' status. This status only exists for manual invoices. If you see this status for an automatically collected invoice, it may mean that the payment attempt had a transaction communication error.

Processing

All invoices that have an ACH bank payment in progress. This status will only exist for ACH bank payments. The status means the associated payment transaction has not settled. An ACH invoice with the Processing status that reaches the due date will not move to Past Due or Paid until the transaction has settled.

Closed

All successfully collected invoices. This status has a value of 'paid' in the export and does not include the 'failed' status. It is important to note that the associated credit card, PayPal, or Amazon transaction with a paid invoice may not be settled with the gateway. Allow at least 1 to 3 business days for transaction settlement with the gateway.

Past Due

All automatic invoices that attempted collection, but the payment failed, or manual invoices that have reached their due date. Payment for automatic invoices will be retried automatically through the dunning process.

Failed

All invoices that have either experienced 20 declines or have been through the dunning process without successful payment. These invoices will not be retried. It is important to note that failed invoices will clear the owed balance from the account and will not attempt any future collections, but the charge line items will still exist in the account history.

Voided

All credit invoices that have been voided. These invoices will not be retried. It is important to note that voided invoices will clear the owed balance from the account and will not attempt any future collections, but the credit line items will still exist in the account history.

Time Range Filter

Created

Sets the date range to the date the invoice was created, which is the 'billed_date' column in the export.

Modified

Sets the date range to the last date the invoice was modified, which is the 'modified_at' column in the export. An invoice is only modified when its 'status' changes.

Export Contents

Column Name
Example
Description

id

b964b5439c2548a489b3a136e75aee9f

Unique internal identifier for the invoice. This is also called the 'invoice_id' or 'uuid' for the invoice in the API.

invoice_number

1291

External invoice identifier.

billed_date

2012-02-19 12:01:33 PST

Creation date of the invoice. Equivalent to date in the deprecated Invoices export. Used for Created date range filter.

due_on

2012-02-19 12:01:33 PST

Date invoice is due. This is the date the net terms is reached.

closed_at

2012-02-19 12:01:33 PST

Date invoice was closed (paid) or failed.

status

pending, processing, past_due, paid, failed, voided

Current status of the invoice. Equivalent to invoice_state in the Adjustments export. See filter notes above for details on what each status means.

net_terms

on-receipt, net-10, net-30, net-60

Identifies the net_terms agreement associated with the invoice. All automatic collection invoices are due 'on-receipt'. Manual collection invoices can have terms of net-10, net-30, net-60, or a custom net day amount.

collection_method

automatic or manual

dentifies whether the invoice fees are collected via manual or automatic invoicing. An automatic invoice means a corresponding transaction is run using the account's billing information at the same time the invoice is created. Manual invoices are created without a corresponding transaction.

account_code

123122E

Account code being charged for this invoice.

account_name

JJ Smith

First and last name from account associated with that invoice.

account_company

Company, Inc.

Company name from account. This field is from the Account Info and is displayed on the invoice if it exists.

account_line1

1 Main Street

Address line 1 of the customer's address on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method.

account_line2

Suite 100

Address line 2 of the customer's address on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method.

account_city

San Francisco

City of the customer's address on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method.

account_state

CA

State or province of the customer's address on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method.

account_zip

94107

ZIP/postal code of the customer's address on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method.

account_country

US

The 2 letter country code for the country of the customer's address on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method.

vat_number

IE124211145

VAT registration number for the customer on the invoice. This will come from the VAT Number field in the Billing Info or the Account Info depending on your tax settings and the invoice collection method.

po_number

AE12523

For manual invoicing, this identifies the Purchase Order number associated with the invoice. This value must be entered by the merchant at the time the invoice is created or it will not exist.

coupon_code

50off

The code for the coupon associated with any discounts on the invoice. This value will only exist if a coupon was applied to the invoice.

currency

USD

The currency of the amounts on the invoice. We do not allow mixed currency invoices.

invoice_total

100

The final total on the invoice. The summation of invoice charges, discounts, credits, and tax. Equivalent to the total in the deprecated Invoices export

invoice_subtotal

50

The Subtotal on the invoice. The summation of charges, discounts, and credits, before tax.

tax_amount

15.00

The total tax amount on the invoice.

tax_type

usst, vat, ca, au, nz

Provides the tax type as "vat" for EU VAT, "usst" for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries.

tax_region

NY, FR, GST, VAT

Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST.

tax_rate

0.1

Tax rate applied on the invoice.

credit_to_account

0

Amount of credit applied back to the account. This amount is a charge with adjustment_origin of 'carryforward' on the invoice. This charge is what zeros out the invoice and should be filtered out of your reports. Credit to Account also maps to the uninvoiced credit that is created for the same amount and left on the account for payment of a future invoice. That credit will have an adjustment_origin that matches the original charge's origin.

recovery_reason

exp_date, retry, account_updater, prior_recovery, customer_updates

If the initial transaction failed but a subsequent one succeeded, this field indicates why. See the details of what each reason means in our blog "Revenue Recovery: What Has Recurly Recovered for Me Lately?".

invoice_country

FR

This column is only visible if your site has European Union VAT or New Zealand GST Location Validation enabled. Column shows the EU or NZ country code of the customer's address on the invoice. The country refers to the evidence_matched.

evidence_matched

Account Info Country, Billing Info Country, IP Address Country, Credit Card BIN Country

This column is only visible if your site has European Union VAT or New Zealand GST Location Validation enabled. Column shows the two pieces of evidence that matched when the invoice was created. The corresponding country is the invoice_country.

modified_at

2014-12-26 08:23:34 PST

The date the invoice was last modified. An invoice is only modified if the status changes. Used for Modified date range filter.

invoice_type

purchase, refund, renewal, immediate_change, termination, credit, gift_card, write_off, external_refund, carryforward_credit, carryforward_gift_credit, usage_correction, import

This is the invoice origin. The original invoice will have a type of 'purchase'. Any refunds or voids will create a negative invoice to cancel out the original. This negative invoice will have a type of 'refund'.


All other invoice types are unlocked only when the Credit Invoices feature is enabled. See the full table of invoice origins for descriptions.

original_invoice_number

1002

If the row is a refund invoice, this value will exist and show the invoice number of the purchase invoice the refund was created from.

ship_address_name

Julie Smith

The first and last name associated with the shipping address

ship_address_line1

ship_address_line1

ship_address_line1

ship_address_line2

Apt 1

The second line of the street address for the shipping address

ship_address_city

West Bloomfield

The city for the shipping address

ship_address_state

MI

The state for the shipping address

ship_address_zip

48322

The zip or postal code for the shipping address

ship_address_country

US

The country for the shipping address

ship_address_phone

248-555-1212

The phone number associated with the shipping address

invoice_doc_type

legacy, charge, credit

This is the invoice document type. All invoices created before the Credit Invoices feature is enabled will have a type of ‘legacy’. Once Credit Invoices is enabled, new invoices will be either ‘charge’ or ‘credit’.

invoice_balance

50.25

The balance of the invoice.
This column will be null until Recurly's Credit Invoices feature is enabled on your Recurly site.

invoice_balance_modified_at

2016-01-01 10:17:02 UTC

The datetime the invoice_balance last changed due to a transaction or credit payment.
This column will be null until Recurly's Credit Invoices feature is enabled on your Recurly site.

invoice_discount

10

The total of all discounts on the invoice. This is the sum of each adjustment’s discount.

invoice_subtotal_before_discounts

50.25

The total of all adjustments on the invoice, before discounts and taxes.

invoice_refundable_amount

50.25

The refundable amount of the invoice, which is the invoice total, including discounts and tax, minus all credit invoices issued against it.
This column will be null until Recurly's Credit Invoices feature is enabled on your Recurly site.

Invoices - Unused Numbers

The unused invoice number export contains basic information for all invoice numbers that were not used on successfully-generated invoices. An unused invoice number could result from a failed sign-up, among other events.

This log of unused invoice numbers is especially useful for audit purposes. It complements the invoice numbers provided in the Invoices - Summary export to provide an explanation for each invoice number in your sequence.

All invoice numbers unsuccessfully attempted on or after July 1, 2019 will be shown in this export.

Column Name
Example
Description

invoice_number

1291

External invoice identifier.

invoice_type

purchase, refund, renewal, immediate_change, termination, credit, gift_card, write_off, external_refund, carryforward_credit, carryforward_gift_credit, usage_correction, import

This is the invoice origin. The original invoice will have a type of 'purchase'. Any refunds or voids will create a negative invoice to cancel out the original. This negative invoice will have a type of 'refund'.


All other invoice types are unlocked only when the Credit Invoices feature is enabled. See the full table of invoice origins for descriptions.

invoice_doc_type

legacy, charge, credit

This is the invoice document type. All invoices created before the Credit Invoices feature is enabled will have a type of ‘legacy’. Once Credit Invoices is enabled, new invoices will be either ‘charge’ or ‘credit’.

invoice_date

2019-07-19 12:01:33 PST

Attempted creation date of the invoice.
The earliest invoice date possible is July 1, 2019, as this is the release date of this export.

Invoices (DEPRECATED)

The Invoices export has been replaced by the new "Invoices - Summary" export and the "Adjustments" export. THIS EXPORT WILL BE REMOVED WHEN YOUR SITE STARTS TO UTILIZE CREDIT MEMOS FUNCTIONALITY

The invoice export contains individual invoice line items including summary totals for invoices, so multiple items may be associated with the same invoice ID.

Invoice Status Filter

All

Every invoice generated within your Recurly site, regardless of status.

Open

All invoices that have not received a payment attempt. Open is equivalent to 'pending' in the new invoice exports and does not include the 'past_due' status. This status only exists for manual invoices. If you see this status for an automatically collected invoice, it may mean that the payment attempt had a transaction communication error.

Processing

All invoices that have an ACH bank payment in process. This status will only exist for ACH bank payments. The status means the associated payment transaction has not settled. An ACH invoice with the Processing status that reaches the due date will not move to Past Due or Paid until the transaction has settled.

Closed

All successfully collected invoices. Closed is equivalent to 'paid' in the new invoice exports and does not include the 'failed' status. It is important to note that the associated credit card, PayPal, or Amazon transaction with a Closed invoice may not be settled with the gateway. Allow at least 1 to 3 business days for transaction settlement with the gateway.

Past Due

All automatic invoices that attempted collection, but payment failed, or manual invoices that have reached their due date. Payment for automatic invoices will be retried automatically through the dunning process.

Failed

All invoices that have either experienced 20 declines, or have been through the dunning process without successful payment. These invoices will not be retried. It is important to note that failed invoices will clear the owed balance from the account and will not attempt any future collections, but the charge line items will still exist in the account history.

Time Range Filter

Created

Sets the date range to the date the invoice was created, which is the 'date' column in the export.

Modified

Sets the date range to the last date the invoice was modified, which is the 'modified_at' column in the export. An invoice is only modified when its 'status' changes.

Export Contents

Column Name
Example
Description

id

b964b5439c2548a489b3a136e75aee9f

Unique internal identifier for the invoice. This is also called the 'invoice_id' or 'uuid' for the invoice in the API.

account_code

123122E

Account code being charged for this invoice.

account_name

JJ Smith

First and last name from account,

invoice_number

1291

External invoice identifier.

subscription_id

1fed8d153fcf4ea2a1d55ff2eebd51b7

Subscription UUID associated with this line item on the invoice.

plan_code

basic

The plan code for the plan associated with the subscription. This value will exist for plan fee, setup fee, add-on fee and free trial line items. This value will not exist for custom charges, custom credits, or open amount refund credits.

coupon_code

50off

The code for the coupon associated with any discounts on the invoice. This value will only exist if a coupon was applied to the invoice and will show for all line items on an invoice, even if the specific line item was not discounted by the coupon.

total

100

The final total on the invoice. The summation of invoice charges, discounts, credits, and tax. Equivalent to the invoice_total in the Invoices - Summary export

subtotal

50

Total charges on the invoice before discounts, credits, and tax.

tax_amount

12.25

The total tax amount on the invoice. This is not the tax amount for the specific line item.

currency

USD

The currency of the amounts on the invoice. Every line item on an invoice will have the same currency. We do not allow mixed currency invoices.

date

2012-02-19 12:01:33 PST

Creation date of the invoice. Equivalent to billed_date in the Invoices - Summary export. Used for Created date range filter.

status

open, processing, past_due, closed, or failed

Current status of the invoice. Equivalent to invoice_state in the Adjustments export and status in the Invoices - Summary export. See filter notes above for details on what each status means.

closed_at

2012-01-18 11:47:13 PST

Date invoice was closed (paid) or failed.

purchase_country

IE

The 2 letter country code for the country of the customer on the invoice. This will come from the Billing Address or the Account Address depending on your tax settings and the invoice collection method. Equivalent to account_country in the Invoices - Summary export.

vat_number

IE124211145

VAT registration number for the customer on the invoice. This will come from the VAT Number field in the Billing Info or the Account Info depending on your tax settings and the invoice collection method.

line_item_total

500

The total amount of the line item after discounts and taxes [(quantity x price) + discount + tax]. Equivalent to adjustment_total in the Adjustments export.

line_item_description

Basic Plan, one month

Description for a specific invoice line item. This is automatically generated for all plan line items. This is custom for one-time custom charges and credits. Equivalent to adjustment_description in the Adjustments export.

line_item_origin

plan, plan_trial, setup_fee, add_on, debit, one_time, credit, carryforward

The original source for a line item. A credit created from an original charge will have the value of the charge's origin. Equivalent to adjustment_origin in the Adjustments export. (plan = subscription fee, plan_trial = trial period 0 amount charge, setup_fee = subscription setup fee, add_on = subscription add-on fee, debit = custom charge through the UI or Adjustments API, one_time = custom charge through the Transactions API, credit = custom credit, carryforward = the charge that zeros out a negative invoice and should be ignored)

line_item_product_code

0000yearly

Plan code for a specific invoice line item. This will only populate if the line item is for a subscription. The value will always be the plan_code, unless the line item is an add-on, which would then show the add-on code. Equivalent to adjustment_product_code in the Adjustments export.

line_item_accounting_code

0000yearly

Internal accounting code for a specific invoice line item. This value will only populate if you define an accounting code for the line item. Accounting codes can be defined for all line items except free trials, which will inherit the plan's accounting code. Equivalent to adjustment_accounting_code in the Adjustments export.

line_item_start_date

2012-01-19 11:03:23 PST

Bill cycle start date for a specific invoice line item. Equivalent to adjustment_start_at in the Adjustments export.

line_item_end_date

2012-02-19 11:03:23 PST

Bill cycle end date for a specific invoice line item. This date will not exist for custom charges (one-time). Equivalent to adjustment_end_at in the Adjustments export.

net_terms

on-receipt, net-10, net-30, net-60

Identifies the net_terms agreement associated with the invoice. All automatic collection invoices are due 'on-receipt'. Manual collection invoices can have terms of net-10, net-30, net-60, or a custom net day amount.

po_number

213123

For manual invoicing, this identifies the Purchase Order number associated with the invoice. This value must be entered by the merchant at the time the invoice is created or it will not exist.

collection_method

automatic or manual

Identifies whether the invoice fees are collected via manual or automatic invoicing. An automatic invoice means a corresponding transaction is run using the account's billing information at the same time the invoice is created. Manual invoices are created without a corresponding transaction. The merchant must enter a manual payment transaction or have the customer pay the invoice with an automatic method, like credit card, PayPal, Amazon, or ACH bank payment.

line_item_uuid

293f96f8c6fd1f8f622ec44306a3a92a

Provides the unique internal identifier for each line item on an invoice. Equivalent to uuid in the Adjustments export.

tax_type

usst, vat, ca, au, nz

Provides the tax type as "vat" for EU VAT, "usst" for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries.

tax_region

NY, FR, GST, VAT

Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST.

tax_rate

0.1

Tax rate applied on the invoice

discount

-5

Total discount amount applied on an invoice. This is not the discount for the specific line item.

original_adjustment_uuid

b964b5439c2548a489b3a136e75aee9f

Value is the uuid of the previous related line item (adjustment). Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund.

modified_at

2014-12-26 08:23:34 PST

The date the invoice was last modified. An invoice is only modified if the status changes. Used for Modified date range filter.

invoice_type

purchase, refund

The original invoice will have a type of 'purchase'. Any refunds or voids will create a negative invoice to cancel out the original. This negative invoice will have a type of 'refund'.

original_invoice_number

1002

If the row is a line item from a refund invoice, this value will exist and show the invoice number of the purchase invoice the refund was created from.

Invoices Exports


Suggested Edits are limited on API Reference Pages

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