Sales taxes

Navigate the complexities of global sales tax with Recurly's comprehensive guide. From the U.S. to the EU, understand rates, rules, and best practices for seamless tax collection.

Introduction to sales tax

Recurly is a best-in-class subscription billing platform. We partner with Avalara and Vertex to enable our merchants to bill for and collect sales taxes across the world.

This page describes our basic taxation functionality, Recurly Taxes, through which we partner with Avalara to white-label their services. Recurly Taxes enables basic sales tax compliance use cases, and certain geographies.

  • Recurly taxes does not support geographies not listed on this page. If you need global sales tax support, we recommend you use the Direct Integration with Avalara AvaTax.
  • Recurly taxes supports tax-inclusive pricing via Avalara AvaTax, Vertex, as well as via Recurly's In-The-Box taxes. Tax Inclusive Pricing
  • Recurly taxes does not support communications taxes and surcharges. If you require this capability, we recommend you use our integration with Avalara for Communications.

Recurly are not taxation experts. We build tools which allow merchants to comply with local sales tax and VAT laws, but do not certify tax compliance in any way.

If you require advice about which laws apply to your business, we recommend that you contact a sales tax professional, who can advise you on the local laws in the areas you serve. If you need a referral to a tax professional, please contact our support team and we will be happy to refer you to a taxation firm who can assist you.


Connect your own Avalara AvaTax Pro or Vertex account for advanced options

  • Many more taxable regions
  • Product taxability rules with tax code mapping past basic physical rates
  • Advanced tax reporting
  • Tax filing

Learn more about Avalara AvaTax Pro and Vertex.

Go live with taxes checklist

To enable tax collection in Recurly, follow these recommended steps. We encourage all merchants to test their tax configurations on a sandbox mode site before completing these steps on their production mode Recurly site.

  1. Determine which customer address you want to tax, the billing address or a physical address.
  2. Clean-up your existing and new customer addresses so that invoices can properly calculate tax when you are ready to go live.
  3. Confirm your own merchant address meets the basic requirements for tax calculations.
  4. Enable the tax countries and or state/provinces where you want to collect tax. This step will reveal tax options on your plan and account pages.
  5. Identify tax exempt customers and mark their account as tax exempt
  6. Edit all existing or new plans that you would like to tax to have "Tax Collected" enabled. This step will start collecting taxes on invoices for new and existing subscribers to the plan.
  7. Update your checkout pages to support tax previews.

Customer addresses and exemption

Taxable address

By default, Recurly will tax based on the customer's Bill To address on the invoice. If you would like to tax based on the physical location of the customer, you have two options:

1. Create and associate a shipping address with the customer's subscription.

This will show a Ship To address on the invoice. Any time there is a Ship To address on the invoice, that address is used as the taxable address. Learn more about shipping addresses.

2. Store the customer's physical address in the Account Information address and enable your Recurly site to use Account Information address as the Bill To address.

Before Recurly added support for shipping addresses, the Account Information address was the original physical address option. By default, the Bill To address on the invoice is set based on the collection method of the invoice. If the collection method is automatic (e.g. - credit card billing), the Bill To uses the Billing Information address. If the collection method is manual (e.g. - issue invoice and pay later with check), the Bill To uses the Account Information address.

If you are doing automatic collection and would like to tax based on the Account Information address, you can configure your Tax Settings to use the account address on the invoice as the Bill To. This will ensure the physical address is used for tax calculations, but still allows the Billing Information address to be used for the payment processing.

To make the Bill To address always the Account Information address on your invoices, go to Configuration > Taxes > Tax Settings > Tax Calculation Address and click the checkbox next to "Use Account Information Address for all Invoices" and click "Save Changes".

If "Use Account Information Address for all Invoices" is enabled, all invoices issued with automatic collection will use the Account Information address and name as the Bill To on the invoice if at least one of the address fields is filled out. If no address field is filled out, the invoice Bill To address will default back to the Billing Information address and name.


Only use one physical address approach

If you take both of the above two approaches for physical address taxation, you will end up with a Bill To address that is always the Account Information address and a Ship To address. Therefore, two physical addresses on the invoice. When it comes to tax calculation, the Ship To address always wins and will be the taxable address for the customer.

Which address fields to collect

In order to calculate tax, you will need to have at least the minimum address fields required for your taxable regions in the customer's taxable address (see above section). Any invoice that does not have the minimum address fields in the customer address will be posted with no tax included.

Minimun address requirements

Recurly's address requirements

As soon as you enable a tax region, Recurly will automatically start requiring a country for all new or updated customer billing addresses, in addition to your Site Settings Address Requirement setting.

The Site Settings Address Requirement does not apply to the Account Information address. If you are taxing based on the Account Information address, make sure you collect and save in Recurly the fields you will need for an accurate tax rate.

Avalara's adress requirements

Avalara accepts a limited character length for each address field, which impacts invoices taxed via Recurly Taxes and Avalara AvaTax Pro. Entering longer address values in Recurly may result in incorrect taxation or taxes not being applied.

Field NameMax Character LengthExample
street address50200 Main Street
address 2100
state / provinceSee Recurly's ISO alpha-2 Codes for accepted region codesCA
countrySee Recurly's ISO alpha-2 Codes for accepted country codesUS
zip / postal code1192614

Countries, provinces and states

Recurly uses ISO alpha-2 country codes on all forms. For example, United Kingdom is "GB", not "UK". Only the United States (US), Canada (CA), Italy (IT) and the Netherlands (NL) will require a state/province if that field is required in your Site Settings Address Requirement. See Recurly's ISO alpha-2 Codes.

Existing customer addresses

Before you start collecting taxes, make sure your existing customers have the minimum address fields required for tax collection in your taxable regions.

Audit existing addresses

We recommend doing an audit of your billing and account addresses and either updating postal code and country for all customers, or at least updating the customers you can tell are in your taxable region and will need tax collected on their invoices once you go live with taxes. You can audit your addresses by exporting the "Accounts" and "Billing Info" exports in the Reports section of your Admin Console.

Inform your customers

Once you enable tax collection, existing customers in taxable regions will start paying taxes on their next invoice. This can be surprising for customers and may result with angry customers contacting you. We strongly recommend contacting your customers to let them know you will be soon collecting tax in their location and they will see taxes on their future invoices.

If you enable tax collection and an existing customer does an immediate subscription change before their first renewal with taxes, you will notice that the subscription change invoice collects taxes on the new charges, but does not mention taxes on the returned credit. This is because the original charge the credit represents was invoiced before you started collecting taxes and did not include tax, so it would be inaccurate to return taxes.

Avalara address validation

Recurly uses Avalara’s address validation tools to ensure that only valid addresses are being used on your taxed invoices. Before creating an invoice, Recurly sends the available address info to Avalara for validation.

For new sign-ups

If Avalara deems the address is invalid, or if the customer’s tax region (also known as a "tax jurisdiction") cannot be determined due to a lack of sufficient address info, the signup will be blocked (neither a subscription or invoice will be created) and one of the following errors will be returned:

  • "The address provided is invalid, could not determine taxing jurisdictions" :this is returned when either a customer's address or the merchant/site's address prove to be invalid or lack sufficient address info.

  • "The state/province provided is invalid, could not apply tax" :this is returned when the state/province in either a customer's address or the merchant/site's address is invalid.

  • "The city provided is invalid, could not apply tax": this is returned when the city in either a customer's address or the merchant/site's address is invalid for the provided country.

For future subscriptions and renewals

The address will still be sent to Avalara for validation. However, rather than blocking an invoice if the address is invalid, the invoice will be created without tax. If a valid address is later provided on the account, tax will be charged appropriately moving forward. Blocking invoices due to insufficient/invalid addresses is only relevant to new sign-ups.

When avalara address validations is used

For merchants using Recurly’s out-of-the-box tax feature, only addresses that fall within your taxable regions will be sent to Avalara for validation. If not enough address info is available to determine the taxable region, the address will not be sent to Avalara. For merchants using their own Avalara AvaTax Pro account, all addresses will be sent to Avalara for validation. If an account has no address, its invoices will be created without tax, and will not be sent through Avalara’s address validation.

Military addresses

If any of your customers use military addresses, please add the term "General Delivery" or "GD" to a spare street address line in the customer's address to ensure their address is properly validated.

Disables avalara address validation for new sign-ups

If necessary, you can disable Avalara's address validation for initial purchases in Configuration > Taxes > Tax Settings > Tax Service Settings. Disable "Require valid address for initial purchases". If validation is disabled, addresses for new sign-ups will still be sent to Avalara to determine tax jurisdiction. However, if an address fails validation, the invoice will still be created (without tax).

Exempt customers

To make a customer account exempt, go to the customer's account page in the Admin Console and edit the Account Information. Check the "Tax Exempt?" box. Once checked all invoices created for the account will not calculate tax.

Your merchant address

Before you can enable a taxable region, you must have the minimum requirements for tax calculation met in your merchant address used on your customer's invoices. The merchant address used on customer invoices and for tax calculations with Avalara is found in the Admin Console under Configuration > Business Entities. You must have at least a postal code and a country for taxes to calculate properly. If you do not have a postal code and country, you will see an error when you try to enable a taxable region.

Tax registration numbers

In the Business Entities configuration, you can set up a default VAT Number and Tax Registration Number which will display on all of the invoices which you send. This applies to your merchant business, there are separate fields available for recording the Tax Registration Numbers for your customers on the account record.

Country-specific tax registration numbers

If you would like to configure different VAT Numbers and Tax Registration Numbers to display on invoices for customers (e.g. if you are registered in Turkey and would like to display both your Turkish VAT number and Tax Registration Number on an invoice to a customer in Turkey) you can do so by clicking the Advanced Settings link and configuring your country-specific Tax Registration Numbers, which can also be reached in Configuration > Taxes > Tax Settings.

Enable a taxable region

Enabling a taxable region will reveal tax collection settings on the plan and account pages, allowing you to configure your product taxability and any customer exemptions. Once a region is enabled, any taxable products and customers will generate tax invoices.

To enable a tax region:

  1. Go to Configurations > Taxes.
  2. Click "Configure" on the country you want to enable.
  3. On the next page for the specific country, select the "Enabled" option.
  4. If the country has state or province sub-regions, you will see these appear and can select the appropriate ones.
  5. Click "Save Changes".
  6. You will see a pop-up confirming you understand that Recurly is using Avalara for tax rate calculations on your production mode invoices. Click "I agree to the above terms" and click "Enable".

Note: While Recurly supports tax calculation for the regions included below, we do not guarantee invoice compliance for each region.


Enable tax regions and taxable plans at beginning of day UTC

Taxable region start and end dates in Avalara do not have times associated with them. Due to this, if you enable taxes in a region mid-day UTC, it is possible that you will have a customer who was invoiced earlier in the day without tax. In the event that you need to refund them, Avalara will try to calculate taxes on the refund and the refund amount may end up larger than the original transaction collected from the customer. This scenario will throw an error and block the refund.

To avoid this issue, please try to enable new taxable regions and relevant taxable plans around beginning of day UTC. If you do experience this issue, contact Recurly Support.

Disable a taxable region

Disabling a taxable region will stop tax collection on future invoices from customers in that location. If a refund is later processed on a taxed invoice from that disabled region, tax will be refunded appropriately because we track the date range where you collected tax in the region.


Do not disable and re-enable a Tax Region in Production Mode

We allow merchants to disable tax regions because they may no longer have a tax obligation in that area. Be careful about mistakenly disabling a tax region because re-enabling it will reset the date range tracked for the region and past invoices will not refund tax correctly. If you get yourself in this situation, please contact Recurly Support.

Supported regions

Âland IslandsDemocratic Republic of the CongoMacedonia (FYROM)
AlbaniaDominican RepublicMartinique
AustraliaGeorgiaNew Zealand
BarbadosEurope (non-EU: all 13 countries)Norway
BelarusEuropean Union (all 28 countries)Russia
Bosnia & HerzegovinaIndonesiaSouth Africa
Burkina FasoIsraelSwitzerland
Canary IslandsKazakhstanThailand
ChinaRepublic of Korea (South)Turkey
Costa RicaKyrgyzstanUnited Arab Emirates
Côte d'IvoireLebanonUnited Kingdom
United States

Supported tax regions and their rates

Tax regions are organized by continent in the tables below.


CountryTax RegionTax RateTax Type
Burkina FasoBF18%VAT
Canary IslandsIC7%VAT
Cape VerdeCV15%GST
Democratic Republic of the CongoCD16%VAT
Cote D'IvoireCI18%VAT
South AfricaZA15%VAT


CountryTax RegionTax RateTax Type
United Arab EmiratesAE5%VAT
Hong KongHK0%GST
Republic of Korea (South)KR10%VAT
Palestine Occupied TerritoryPS16%GST
Sri LankaLK15%GST


Enabling tax collection in Australia will apply 10% GST to all taxable plan, add-on or adjustment line items for customers in Australia.

Tax RegionTax TypeTax RateMinimum Address Requirement


Recurly supports the collection and validation of Australian Business Numbers (ABN) and Australian Company Numbers (ACN). If the customer's country is Australia, the VAT number field will display as "ABN / ACN" on the invoice, Hosted Pages, and in the Admin Console. A value placed in the field, when the country is Australia, will be validated to be 9 or 11 digits and will be saved and displayed in the following formats "000 000 000" or "00 000 000 000" respectively.


Enable ABN validation with Australian Business Register

If you need to identify customer's with an ABN that is both active and GST registered, and exempt them from Australian GST, contact Recurly Support and ask to have ABN validation through the Australian Business Register enabled on your Recurly site. Please see the AU GST on Digital Services section below to learn more about the feature.

AU GST on digital services

On July 1, 2017, Australia started requiring non-resident businesses with digital services sales in Australia past a specific threshold to register and collect GST from Australian customers. This change includes exemption for Australian businesses with an active and GST registered ABN, and the collection of two pieces of location evidence from customers that are taxed.

Cross-border exemption

If you need to identify customer's with an ABN that is both active and GST registered, and exempt them from Australian GST, contact Recurly Support and ask to have ABN validation through the Australian Business Register enabled on your Recurly site. Once enabled, an 11 digit value submitted in the VAT number field (ABN/ACN) where the country is Australia will validate the number with the Australian Business Register's API. If the number is not a real ABN, it will be rejected. If the number is real, it will be saved and Recurly will store whether it is qualified for a tax exemption. An ABN is qualified for a tax exemption if it is both active and GST registered. Note that Recurly does not currently show you if we determined an ABN to be qualified for a tax exemption or not.

When invoicing an Australian customer, if they have an ABN that is qualified for a tax exemption and your Site Settings country is not in Australia (cross-border sale), Recurly will not apply GST to the invoice. Note that a customer could have a real ABN or ACN that does not qualify them for a tax exemption. Recurly will still show the not qualified number on the invoice, but GST will be applied.

Recurly will revalidate an ABN with the Australian Business Register every six months. If a renewal after six months triggers a revalidation and the number is no longer qualified, Recurly will apply GST to the invoice.

Recurly will only validate with the Australian Business Register when your Recurly site is in production mode. While in sandbox mode, you can simulate the response with these test ABNs.

  • 10 120 000 004: Is considered a real ABN that is GST registered and will be exempt from tax.
  • 10 000 000 000: Is considered a real ABN that is not GST registered and will be taxed.
  • 51 824 753 555: Is not a real ABN and will not be saved.
Location Validation

To require two pieces of matching location evidence from taxable Australian customers, enable Recurly's Tax Location Validation for Australia.


Non-european union

Enabling tax collection in a non-EU European country will apply that country's VAT rate to all taxable plan, add-on or adjustment line items for customers in the country.

All countries have a Tax Type of VAT and a Minimum Address Requirement of Country.

Here are all the supported non-EU European countries and their rates:

CountryTax RegionTax RateTax Type
Âland IslandsAX24%VAT
Bosnia and HerzegovinaBA17%VAT
Isle of ManIM0%GST
Macedonia, The Former Yugoslav RepublicMK18%VAT
Northern IrelandXI20%VAT


If you need to collect a State Registration Number instead of a VAT Number, you can contact Recurly Support and we will change your site to display the VAT Number field as "SRN / SRNIE" when the associated address country is Russia. This display will show on the invoice, in the Admin Console, and on the Hosted Pages. Additionally, this feature will validate any value saved in the SRN / SRNIE field to be 13 or 15 digits.

European union

The European Union VAT system has many rules and requirements, so we have created a separate page dedicated to EU VAT. Read the full details on our European Union VAT support here.

LocationTax RegionTax RateTax TypeMinimum Address Requirement
United KingdomGB20%VATCountry


Enabling tax collection in New Zealand will apply 15% GST to all taxable plan, add-on or adjustment line items for customers in New Zealand.

CountryTax RegionTax RateTax TypeMinimum Address Requirement
New ZealandNZ15%GSTCountry

NZ GST on digital services

Starting October 1, 2016, New Zealand required non-resident digital services businesses to collect GST from non-business New Zealand customers and to collect two pieces of matching evidence proving the customer is in New Zealand. To require two pieces of matching location evidence from New Zealand non-business customers, enable Recurly's Tax Location Validation for New Zealand.

Through Recurly, you can collect GST Numbers from New Zealand business customers and correctly not tax invoices where a New Zealand GST Number exists for the customer.

  • Store the GST Number in the VAT Number field of the customer address in Recurly.
  • If the address has a VAT Number and a country of New Zealand, Recurly will require the number to be 8 or 9 digits.
  • On the invoice, Recurly will display "GST Number" instead of "VAT Number" for a New Zealand customer in order to properly label the provided value.
  • If you have New Zealand taxes enabled and your Site Settings country is not in New Zealand, Recurly will not tax an invoice where the customer is in New Zealand and has a value in the VAT Number field.

North America


Enabling tax collection in Canada will apply 5% GST to all taxable plan, add-on or adjustment line items for customers in Canada. Additional province level taxes (PST, HST, or QST) will be applied if you enable the province as a taxable sub-region and the customer is located in that province. If you want to collect only GST from all provinces in Canada, enable Canada, but do not select a province.

Tax RegionTax TypeMinimum Address Requirement
Postal Code and Country

Here are all the Canadian provinces, whether they charge a province level tax, and what that province level tax is called:

Province NameTax Type
British Columbia*GST/PST
New Brunswick*GST/HST
Newfoundland and Labrador*GST/HST
Northwest TerritoriesGST
Nova Scotia*GST/HST
Prince Edward Island*GST/HST
  • If the customer is located in this province, and it is a different province than one you have enabled in your Canada tax settings, then they will only be charged GST.

Note: Some Canadian cities have special exemption rules. For example, Lloydminster city is in two provinces, Alberta and Saskatchewan, so it has a special rule making Lloydminster tax exempt from PST. Avalara will respect these special city level rules. Recurly's tax calculations in sandbox and for production previews are province level and will not show these exceptions to the province rules.

United States

Enabling tax collection in the United States will apply Sales Tax to all taxable plan, add-on or adjustment line items for customers in the states you enable. Sales Tax applies state, county, local and special taxes depending on the customer's invoice address.

The Tax Region for U.S. Sales Tax is always the two letter state code of the tax being applied. This is shown on the invoice next to the combined tax rate.

The Minimum Address Requirement for U.S. Sales Tax is Postal Code and Country.


Collect full street address for more accurate rate calculations

U.S. Sales Tax has complex tax jurisdiction dividing lines that go down to the street address. The house across the street from you can be in the same postal code, but be in a different tax jurisdiction. While a postal code and country are the minimum address requirement for taxes to be calculated, we strongly suggest merchants collect the full street address in order to calculate more accurate tax rates through Avalara.

CountryTax RegionTax RateTax Type
Costa RicaCR13%VAT
Dominican RepublicDO18%VAT
El SalvadorSV13%GST

South America

CountryTax RegionTax RateTax Type
Falkland IslandsFK0%GST
Trinidad And TobagoTT12.5%GST
  • Recurly does not support RUT number validation, format validation, or IP address validation in Chile.

Taxable plans and adjustments


Once you enable a taxable region, you can configure your plans to collect taxes. All existing plans will default to tax exempt. You will need to edit each individual plan that you want to tax to enable the "Collect Tax" option. All new plans created will default to collecting tax. If a plan has "Collect Tax" enabled, any included add-ons will also be taxed.


How to enable a plan to collect tax

One-time charges

Once you enable a taxable region, you can create custom charge adjustments that collect tax. The Create Charge page in the Admin Console for an account will default to collecting tax on charges. Recurly does not support tax calculations on custom credit adjustments.


How to create a charge with tax

Tax product type

Recurly's basic tax calculations through Avalara's AvaTax calculate rates based on treating each line item (plan, add-on, adjustment) with a product distinction of "Tangible Personal Property" (TPP). This is essentially a physical good. In many states and countries, the rules for physical and digital goods, as well as services, all match the TPP rules. It is important for you to confirm that the basic rates calculated meet your taxation requirements. If you need additional product distinctions and taxation rules, you can upgrade by getting your own AvaTax account or Vertex account to use their tax codes for advanced rates and rule mappings.

Tax previews at checkout

Recurly provides tax estimate previews based on internal rate tables. All final invoices calculate tax through Avalara. Tax previews are supported on the Hosted Payment Pages, in the API for Subscriptions and Invoices, and through Recurly.js for subscription sign-ups.

Tax invoices

Invoices with tax will include these three things:

  • A column called "Tax" to the right of Subtotal that displays the tax rate for the specific line item. If tax is not applicable, the rate will show 0.00%
  • A column called "Total" to the right of Tax that displays the amount of the subtotal plus tax for the specific line item.
  • A invoice-level total tax row with the tax region, rate and tax amount for the invoice. This amount will equal the sum of the line item values in the Tax column.

Tax Invoices with multiple tax rates

An invoice may contain more than rate depending on how the item type is taxed and/or if there are multiple shipping addresses that have different tax rates (see Shipping Address per Line Item.

If this is the case, the invoice will include the additional information:

  • A Tax Details card that displays each tax rate, subtotal amount, and the tax amount
  • An invoice-level total tax row that includes only the total tax amount for the invoice since the Tax Details card will contain the other specific information on rates and subtotal amounts.

Tax amount rounding

Tax amount estimates in sandbox mode and previews in production mode are always rounded up to two decimal points. We round up because rounding rules vary for different regions and jurisdictions. Actual invoices in production mode use Avalara for rate calculations. Avalara provides the appropriate rounding up or down for the region and jurisdiction. Avalara rounds on the line item level, not the invoice level. In most regions, normal rounding rules apply where any digit under 5 is rounded down and 5 and higher is rounded up.



  • Invoice rate is HU VAT 27% (Hungary VAT)
  • First line item is $5.79 (raw tax = $1.5633)
  • Second line item is $5.81 (raw tax = $1.5687)

Sandbox Mode and Production Previews

  • First line item tax = $1.57
  • Second line item tax = $1.57
  • Total tax = $3.14

Production Actual Invoice

  • First line item tax = $1.56
  • Second line item tax = $1.57
  • Total tax = $3.13

Tax on credits

The rule with refunded tax is that the full tax being returned should be broken out and documented on a credit memo issued to the customer. When that issued credit is used to pay down a new invoice, the tax amount does not need to be broken out again because the credit is now acting as payment. Keeping this in mind, below is how Recurly handles tax returns on credit in our three different credit scenarios.


Refunds in Recurly create a refund invoice. This is Recurly's version of a credit memo. How you refund will affect the method of tax calculation used.

Line Item Refunds
Recurly will calculate tax on top of the line items you select to refund. Additionally, line item refunds maintain the product identity and will keep the correct refunded tax amount with the associated refunded credit on the refund invoice as well as your "Adjustments" export.

Open Amount Refunds
Also known as Specific Amount Refunds, Recurly will take the refund amount you request and back out the amount of tax to return so that the net refund to the customer is exactly what was requested. If there are multiple line items on the invoice being refunded, the tax being returned will not be associated with any of those line items. Open Amount Refunds are at the invoice level, so all associations with specific line items are lost. Due to this issue, we recommend merchants always use Line Item Refunds unless they absolutely have to refund a custom amount.


Multiple Partial Refunds Rounding Issues

If you do partial refunds that include tax and you ultimately try to refund the entire invoice, you might run into rounding issues where the final partial refund amount is calculating a tax that is a cent or two higher than the original transaction amount. In this scenario, the refund will be blocked with an error. If this happens to you, please contact Recurly Support.

Immeadiate upgrades and downgrades

Immediate subscription changes will always generate an invoice that bills the new version of the subscription prorated for the time remaining and credits the old version of the subscription paid for prorated for the time that will not be used. Traditionally this scenario would require a credit memo for the refunded credit with the tax broken out, and an invoice with new prorated charges and necessary taxes. The credit memo would then help pay down the invoice.

Recurly does not have support for credit memos in the case of an immediate subscription change, so the new charges and refunded credit are both included on the same invoice document and both have taxes broken out. This means that a subscription change invoice can have positive tax on the charges and negative tax on the credit. In this case, the total tax on the invoice will be the net of the charge's tax and the credit's tax. Additionally, the inclusion of the credit as a line item will reduce the invoices overall subtotal, so the subtotal will not always directly correlate to the total tax represented on the invoice.

While the invoice subtotal and total tax may not correlate exactly, the correct tax is ultimately being collected and returned at the line item level. With tax reporting at the line item level through the "Adjustments" export, you should be able to report on the correct tax amounts.

Custom credits adjustments

Recurly does not support tax calculations on custom credit adjustments. If you need to credit a customer and refund tax as part of that credit, you must do a refund instead of issuing a custom credit adjustment.

Tax exports

Recurly provides tax reporting at the line item level in the "Adjustments" export. This export breaks out the state, county, local and special tax rates and amounts calculated by Avalara.

We do not provide special reports or exports for taxes. This is a feature provided by Avalara or Vertex when you upgrade to connecting your own Avalara AvaTax Pro or Vertex account.

Sandbox testing

Most of Recurly's out-of-the-box taxes can be tested on any site in sandbox mode. While in sandbox mode, all preview and final invoices will use Recurly's internal rate tables. In production mode, Avalara will be used for all final invoice tax calculations and Recurly's internal rate tables will only be used for checkout previews. This means in sandbox mode you will not be able to test Avalara's Address Validation and you might see slight variations in tax rates applied.

Avalara downtime

When an invoice is created and a Recurly site is enabled to collect tax in the customer's location, Recurly will send a request to Avalara for the tax to include on the invoice. In the event that Recurly cannot get a successful response from Avalara or the internal Recurly tax service that talks to Avalara is unresponsive, Recurly will respond differently depending on whether the invoice is for a new sign-up or purchase, or for a future subscription activation or renewal.

To check Avalara's status, visit and expand the Avalara AvaTax section to view the "Tax Calculation Service".

For new sign-ups and purchases

If Recurly cannot get a successful response from Avalara or the internal Recurly tax service that talks to Avalara is unresponsive, the signup or purchase will be blocked (neither a subscription or invoice will be created). This is to ensure that no invoice for a customer in a taxable location is created without a tax consideration. The following error will be returned:

  • "Tax service currently unavailable, please try again later"

Disables tax response requirement for inital purchases

If you would prefer to allow new sign-ups and purchases to go through when tax cannot be calculated, you can change the default behavior for your site by going to Configuration > Taxes > Tax Settings > Tax Service Settings and disabling "Require successful tax response for initial purchases".

If you disable the tax response requirement, invoices will be created without tax when Avalara or Recurly's internal tax service is unresponsive or in the tax service returns an error other than invalid address. Recurly will not notify you when an invoice is created without a tax consideration. To track these invoices, you will need to use the Invoices - Summary export or Invoices API to identify invoices in locations where you tax and no tax was charged on the invoice.

It is important to note that it is not possible to charge a customer only the missing tax after an invoice is created. The only way to collect the missing tax would be to refund the invoice and issue a new custom charge invoice. The custom charge invoice, while linked to the account, will not be linked to the subscription or underlying plan. Due to this, we recommend that merchants disabling the tax response requirement only do so if they plan to take on the missing tax fees themselves, and not collect the missing tax from the customer.

For future subscriptions and renewals

If Recurly cannot get a response from Avalara or the internal Recurly tax service that talks to Avalara is unresponsive, Recurly will not activate a future subscription or renew an existing subscription and will keep retrying the activation or renewal every hour until a response is received from Avalara. We retry the activation and renewal to ensure that no invoice for a customer in a taxable location is created without a tax consideration. While the renewal may happen an hour late, the underlying subscription dates will respect the original subscription billing cycle. This functionality, unlike sign-ups and purchases, cannot be configured or changed.

If Avalara or the internal Recurly tax service return an error during a renewal, the renewal will go through successfully, creating an invoice without tax.


There is a field included in the API, a column in exports, and a note in the UI if tax service was used or not. The field in the API and Exports is a boolean field called used_tax_service. In the UI, the invoice will display a note if tax service was used or not.