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    

Adjustments Exports

Adjustments V2

Version Created: 5/2/19
Version Updates Summary:

  • Column added for Shipping Method

Recurly provides two exports to help you retrieve data related to adjustments that have been invoiced as line items or are still uninvoiced on the account: Adjustments and Adjustment - Coupons

Adjustments

The Adjustments export contains each invoiced charge and credit adjustment, with the option to include uninvoiced adjustments currently on the account. To access the Adjustments export, visit the Exports page under Reports in your Recurly site.

Options

You have two options for exporting the data:

Include uninvoiced adjustments

By default, this export will only include invoiced adjustments. If this option is selected, the export will include charges and credits on an account that have not been invoiced yet. Uninvoiced charges and credits created on the account in the date range you specify will appear in the export. These adjustments will appear at the top of the export with an adjustment_status of 'pending'.

Use invoice posted date

By default, this export will use the Created date of the adjustment, not the invoice. This means that an uninvoiced charge or credit created on the account on an older date, but invoiced in the date range you select will not show up in the export. If you would like to see all charges and credits invoiced in the date range you specify, select this option to use the invoice posted date. Any uninvoiced adjustments included in the export will exist depending on their creation date, since there is no invoice date to use.

Time Range Filter

Created

This export is set to use the creation date of the charge and credit adjustment. This is equivalent to the adjustment_created_at column.
To use the invoice creation date, select the option "Use invoice date" mentioned above.

Note that adjustments cannot be modified, therefore there is not a "modified' time range option.

Export Contents

Column Name
Example
Description

uuid

b964b5439c2548a489b3a136e75aee9f

Unique internal identifier for the adjustment. Equivalent to line_item_uuid in the deprecated Invoices export.

account_code

123122E

Account code being charged for this invoice.

subscription_id

1fed8d153fcf4ea2a1d55ff2eebd51b7

Subscription UUID associated with this adjustment on the invoice.

invoice_id

4bdb2171cebe4ecfb0cb129bd1a65746

Unique internal identifier for the invoice. This is called the 'id' in the Invoices - Summary export or 'uuid' for the invoice in the API.

adjustment_status

invoiced or pending

Current status of the adjustment. Pending adjustments are charges or credits on an account that have not been applied to an invoice yet. Invoiced adjustments will always have an invoice associated with them.

adjustment_type

charge or credit

Charges are positive adjustments that debit the account. Credits are negative adjustments that credit the account.

adjustment_created_at

2012-02-19 12:01:33 PST

Creation date of the adjustment. This date will equal the billed_date of the invoice in most cases, but will be older than the billed_date if the adjustment was created on the account a period of time before it was invoiced. The adjustment_created_at date will never be after the invoice's billed_date.

adjustment_start_at

2012-02-19 12:01:33 PST

Bill cycle start date for a specific adjustment. Equivalent to line_item_start_date in the deprecated Invoices export.

adjustment_end_at

2012-02-19 12:01:33 PST

Bill cycle end date for a specific adjustment. Equivalent to line_item_end_date in the deprecated Invoices.

adjustment_description

Gold Plan

Description for a specific adjustment. This is automatically generated for all plan adjustments. This is custom for one-time custom charges and credits. Equivalent to line_item_description in the deprecated Invoices export

adjustment_quantity

1

Quantity of the adjustment.

adjustment_currency

USD

Currency of the adjustment.

adjustment_amount

100

Adjustment amount, before discounts or taxes.

adjustment_total

50

The total amount of the adjustment after discounts and taxes [(quantity x price) + discount + tax]. Equivalent to line_item_total in the deprecated Invoices.

adjustment_taxable

0 or 1

0 indicates adjustment is not taxable, 1 indicates adjustment is taxable.

adjustment_discount

5

The discount applied to the adjustment.

adjustment_tax

5

The tax amount for the adjustment.

adjustment_accounting_code

X100

Internal accounting code for a specific adjustment. This value will only populate if you define an accounting code for the adjustment. Accounting codes can be defined for all adjustments except free trials, which will inherit the plan's accounting code. Equivalent to line_item_accounting_code in the deprecated Invoices export.

adjustment_product_code

gold

Product code for a specific adjustment. This will populate automatically with the plan code or add-on code if the adjustment is for a subscription. This will populate for custom charges and credits (origin = debit or one_time) if a value was set when the adjustment was created. Equivalent to line_item_product_code in the deprecated Invoices export.

adjustment_tax_code

P0000000, physical

Tax code is a field associated with the adjustment that we send to Avalara for tax calculations. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own Avalara AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

adjustment_origin

plan, plan_trial, setup_fee, add_on, add_on_trial, usage_add_on, usage_add_on_trial, one_time, debit, credit, coupon, carryforward, gift_card, external_gift_card

The original source for an adjustment. A credit created from an original charge will have the value of the charge's origin. Equivalent to line_item_origin in the deprecated Invoices 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)

tax_type

usst, vat, ca, au, nz

Tax type for the adjustment. Will be "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

The tax region for the adjustment. 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.09

Tax rate applied to the adjustment.

tax_amount

5

The tax amount for the adjustment. This column is the same as the adjustment_tax column, but tax_amount may be missing a few values for merchants who have used Recurly's older VAT feature (pre-2015). Merchants who used the old VAT feature should use the adjustment_tax column for older reports.

country_juris

united states, germany, australia

Country tax jurisdiction of the adjustment. This will be the full name of the country in lowercase.

country_rate

0

Country tax rate of the adjustment. This is the tax rate that corresponds to the country_juris and country_amount.

country_amount

0

Country tax amount of the adjustment. This is the tax amount that corresponds to country_rate and country_juris.

state_juris

california, ontario

State or province tax jurisdiction of the adjustment. This will be the full name of the state or province in lowercase.

state_rate

0.065

State or province tax rate of the adjustment. This is the tax rate that corresponds to the state_juris and state_amount.

state_amount

0.33

State or province tax amount of the adjustment. This is the tax amount that corresponds to state_rate and state_juris.

county_juris

san mateo

County tax jurisdiction of the adjustment. This will be the full name of the county in lowercase.

county_rate

0.01

County tax rate of the adjustment. This is the tax rate that corresponds to the county_juris and county_amount.

county_amount

0.05

County tax amount of the adjustment. This is the tax amount that corresponds to county_rate and county_juris.

city_juris

san francisco

City tax jurisdiction of the adjustment. This will be the full name of the city in lowercase.

city_rate

0.1

City tax rate of the adjustment. This is the tax rate that corresponds to the city_juris and city_amount.

city_amount

0.05

City tax amount of the adjustment. This is the tax amount that corresponds to city_rate and city_juris.

special_juris

san francisco

Special tax jurisdiction of the adjustment. This will be the full name of the jurisdiction in lowercase.

special_rate

0.1

Special jurisdiction tax rate of the adjustment. This is the tax rate that corresponds to the special_juris and special_amount.

special_amount

0.05

Special jurisdiction tax amount of the adjustment. This is the tax amount that corresponds to special_rate and special_juris.

adjustment_refund

TRUE, FALSE

TRUE indicates that the adjustment is a refund of a charge. FALSE indicates that the adjustment was a standard charge.

original_adjustment_uuid

b964b5439c2548a489b3a136e75aee9f

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

invoice_number

1291

Invoice number of the invoice the adjustment was on.

invoice_state

pending, processing, past_due, paid, failed, voided

Current state of the invoice the adjustment was on. Equivalent to invoice_status in the Invoices - Summary export.

adjustment_coupon_code

1monthfree-K09SC9R8

The coupon code that discounted the specific adjustment_discount amount on the adjustment.

invoice_billed_date

2012-02-19 12:01:33 PST

Creation date of the invoice. Equivalent to date in the deprecated Invoices export.

invoice_closed_at

2012-02-19 12:01:33 PST

Date invoice was paid or failed.

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

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

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

invoice_type

purchase or 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'.

account_name

JJ Smith

First and last name from account.

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.

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

adjustment_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 adjustments. This value will not exist for custom charges, custom credits, or open amount refund credits.

original_invoice_number

1002

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

invoice_due_on

2012-02-19 12:01:33 PST

The due date of the invoice.

adjustment_subtotal

50.25

The adjustment amount after discounts, but before taxes.

adjustment_credit_reason_code

general, service, promotional, refund, write_off, gift_card

The credit reason code of the adjustment. This is a new attribute with Recurly defined values the merchant can choose from when creating custom credits, or Recurly will set when issuing credits.
This column will be null until Recurly's Credit Invoices feature is enabled on your Recurly site.

adjustment_refundable_amount

50.25

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

ship_address_name

Jane Doe

The first and last name associated with the shipping address for the adjustment.

ship_address_line1

123 Main Street

The first address line associated with the shipping address for the adjustment

ship_address_line2

Suite #202

The second address line associated with the shipping address for the adjustment

ship_address_city

San Francisco

The city associated with the shipping address for the adjustment.

ship_address_state

CA

The state associated with the shipping address for the adjustment.

ship_address_zip

94110

The zip code associated with the shipping address for the adjustment

ship_address_country

US

The country ISO code associated with the shipping address for the adjustment

ship_address_phone

510-100-1000

The phone number associated with the shipping address for the adjustment

Adjustments - Coupons

This export will only show on the Exports page if you have Multiple Coupons Per Account enabled under Coupon Settings.

The Adjustments - Coupons export matches the regular Adjustments export, except there is a row for each charge or credit's discount. This export is useful for merchants allowing multiple active coupons on an account. If there are multiple coupon discount's on a single adjustment, this export will show how much of the discount came from each coupon redemption applied. To access the Adjustments - Coupons export, vist the Exports page under Reports in your Recurly site.

Options

You have two options for exporting the data:

Include uninvoiced adjustments

By default, this export will only include invoiced adjustments. If this option is selected, the export will include charges and credits on an account that have not been invoiced yet. Uninvoiced charges and credits created on the account in the date range you specify will appear in the export. These adjustments will appear at the top of the export with an adjustment_status of 'pending'.

Use invoice posted date

By default, this export will use the Created date of the adjustment, not the invoice. This means that an uninvoiced charge or credit created on the account on an older date, but invoiced in the date range you select will not show up in the export. If you would like to see all charges and credits invoiced in the date range you specify, select this option to use the invoice posted date. Any uninvoiced adjustments included in the export will exist depending on their creation date, since there is no invoice date to use.

Time Range Filter

Created

This export is set to use the creation date of the charge and credit adjustments. This is equivalent to the adjustment_created_at column. To use the invoice creation date, select the option "Use invoice date" mentioned above.

Modified

This option is not supported for the Adjustments - Coupons export.

Export Contents

Column Name
Example
Description

uuid

b964b5439c2548a489b3a136e75aee9f

Unique internal identifier for the adjustment. Equivalent to line_item_uuid in the deprecated Invoices export.

account_code

123122E

Account code being charged for this invoice.

subscription_id

1fed8d153fcf4ea2a1d55ff2eebd51b7

Subscription UUID associated with this adjustment on the invoice.

invoice_id

4bdb2171cebe4ecfb0cb129bd1a65746

Unique internal identifier for the invoice. This is called the 'id' in the Invoices - Summary export or 'uuid' for the invoice in the API.

adjustment_status

invoiced or pending

Current status of the adjustment. Pending adjustments are charges or credits on an account that have not been applied to an invoice yet. Invoiced adjustments will always have an invoice associated with them.

adjustment_type

charge or credit

Charges are positive adjustments that debit the account. Credits are negative adjustments that credit the account.

adjustment_created_at

2012-02-19 12:01:33 PST

Creation date of the adjustment. This date will equal the billed_date of the invoice in most cases, but will be older than the billed_date if the adjustment was created on the account a period of time before it was invoiced. The adjustment_created_at date will never be after the invoice's billed_date.

adjustment_start_at

2012-02-19 12:01:33 PST

Bill cycle start date for a specific adjustment. Equivalent to line_item_start_date in the deprecated Invoices export.

adjustment_end_at

2012-02-19 12:01:33 PST

Bill cycle end date for a specific adjustment. Equivalent to line_item_end_date in the deprecated Invoices.

adjustment_description

Gold Plan

Description for a specific adjustment. This is automatically generated for all plan adjustments. This is custom for one-time custom charges and credits. Equivalent to line_item_description in the deprecated Invoices export

adjustment_quantity

1

Quantity of the adjustment.

adjustment_currency

USD

Currency of the adjustment.

adjustment_amount

100

Adjustment amount, before discounts or taxes.

adjustment_total

50

The total amount of the adjustment after discounts and taxes [(quantity x price) + discount + tax]. Equivalent to line_item_total in the deprecated Invoices.

adjustment_taxable

0 or 1

0 indicates adjustment is not taxable, 1 indicates adjustment is taxable.

adjustment_discount

5

The discount applied to the adjustment that comes from the specific coupon redemption in adjustment_coupon_code.

adjustment_tax

5

The tax amount for the adjustment.

adjustment_accounting_code

X100

Internal accounting code for a specific adjustment. This value will only populate if you define an accounting code for the adjustment. Accounting codes can be defined for all adjustments. Plan set-up fees and plan free trial charges will inherit the plan's accounting code. Equivalent to line_item_accounting_code in the deprecated Invoices export.

adjustment_product_code

gold

Product code for a specific adjustment. This will populate automatically with the plan code or add-on code if the adjustment is for a subscription. This will populate for custom charges and credits (origin = debit or one_time) if a value was set when the adjustment was created. Equivalent to line_item_product_code in the deprecated Invoices export.

adjustment_tax_code

P0000000, physical

Tax code is a field associated with the adjustment that we send to Avalara for tax calculations. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own Avalara AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

adjustment_origin

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

The original source for an adjustment. A credit created from an original charge will have the value of the charge's origin. Equivalent to line_item_origin in the deprecated Invoices 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)

tax_type

usst, vat, ca, au, nz

Tax type for the adjustment. Will be "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

The tax region for the adjustment. 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.09

Tax rate applied to the adjustment.

tax_amount

5

The tax amount for the adjustment. This column is the same as the adjustment_tax column, but tax_amount may be missing a few values for merchants who have used Recurly's older VAT feature (pre-2015). Merchants who used the old VAT feature should use the adjustment_tax column for older reports.

country_juris

united states, germany, australia

Country tax jurisdiction of the adjustment. This will be the full name of the country in lowercase.

country_rate

0

Country tax rate of the adjustment. This is the tax rate that corresponds to the country_juris and country_amount.

country_amount

0

Country tax amount of the adjustment. This is the tax amount that corresponds to country_rate and country_juris.

state_juris

california, ontario

State or province tax jurisdiction of the adjustment. This will be the full name of the state or province in lowercase.

state_rate

0.065

State or province tax rate of the adjustment. This is the tax rate that corresponds to the state_juris and state_amount.

state_amount

0.33

State or province tax amount of the adjustment. This is the tax amount that corresponds to state_rate and state_juris.

county_juris

san mateo

County tax jurisdiction of the adjustment. This will be the full name of the county in lowercase.

county_rate

0.01

County tax rate of the adjustment. This is the tax rate that corresponds to the county_juris and county_amount.

county_amount

0.05

County tax amount of the adjustment. This is the tax amount that corresponds to county_rate and county_juris.

city_juris

san francisco

City tax jurisdiction of the adjustment. This will be the full name of the city in lowercase.

city_rate

0.1

City tax rate of the adjustment. This is the tax rate that corresponds to the city_juris and city_amount.

city_amount

0.05

City tax amount of the adjustment. This is the tax amount that corresponds to city_rate and city_juris.

special_juris

san francisco

Special tax jurisdiction of the adjustment. This will be the full name of the jurisdiction in lowercase.

special_rate

0.1

Special jurisdiction tax rate of the adjustment. This is the tax rate that corresponds to the special_juris and special_amount.

special_amount

0.05

Special jurisdiction tax amount of the adjustment. This is the tax amount that corresponds to special_rate and special_juris.

adjustment_refund

TRUE, FALSE

TRUE indicates that the adjustment is a refund of a charge. FALSE indicates that the adjustment was a standard charge.

original_adjustment_uuid

b964b5439c2548a489b3a136e75aee9f

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

invoice_number

1291

Invoice number of the invoice the adjustment was on.

invoice_state

paid

Current state of the invoice the adjustment was on. State can be: pending, processing, past_due, paid, or failed. Equivalent to invoice_status in the Invoices - Summary export.

adjustment_coupon_code

1monthfree-K09SC9R8

The coupon code that discounted the adjustment.

invoice_billed_date

2012-02-19 12:01:33 PST

Creation date of the invoice. Equivalent to date in the deprecated Invoices export.

invoice_closed_at

2012-02-19 12:01:33 PST

Date invoice was paid or failed.

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

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

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

invoice_type

invoice_type

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

account_name

JJ Smith

First and last name from account.

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.

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

adjustment_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 adjustments. This value will not exist for custom charges, custom credits, or open amount refund credits.

original_invoice_number

1002

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

invoice_due_on

2012-02-19 12:01:33 PST

The due date of the invoice.

adjustment_subtotal

50.25

The adjustment amount after discounts, but before taxes.

adjustment_credit_reason_code

general, service, promotional, refund, write_off, gift_card

The credit reason code of the adjustment. This is a new attribute with Recurly defined values the merchant can choose from when creating custom credits, or Recurly will set when issuing credits.
This column will be null until Recurly's Credit Invoices feature is enabled on your Recurly site.

adjustment_refundable_amount

50.25

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

shipping_method_code

usps-overnight

The Shipping Method code used when the Shipping Method was created.

Adjustments Exports


Suggested Edits are limited on API Reference Pages

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