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    

Taxes

Start collecting taxes on your Recurly invoices. Configure where you have a tax obligation and how your plans should be taxed. Using Avalara AvaTax for rate calculations, Recurly will automatically collect tax on the appropriate customer invoices.

Feature Overview

Recurly has partnered with Avalara to provide basic tax rate calculations out-of-the-box with your Recurly subscription.

  • Avalara's AvaTax basic physical rate calculations for 47 countries (basic digital for European Union)
  • Configure taxable regions at the country and state/province level
  • Configure taxable plans
  • Tax based on the billing address or physical address
  • Avalara's address validation for accurate customer address collection at the time of subscribing
  • Ability to mark an account as tax exempt

Connect your own Avalara AvaTax or Vertex O Series 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.
Learn more about Vertex O Series.

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

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

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.

TELL YOUR CUSTOMERS YOU ARE GOING TO COLLECT TAX

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 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 a customer's address proves to be invalid, or lacking sufficient address info.

  • "The site configured address is invalid, could not determine taxing jurisdictions" -- this is returned when the merchant/Recurly site's address proves to be invalid, or lacking sufficient address info.

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

  • "The site configured state/province is incorrect" -- this is returned when the merchant/Recurly site's state/province is invalid.

  • "The city provided is invalid, could not apply tax" -- this is returned when the city in a customer'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 signups.

WHEN AVALARA ADDRESS VALIDATION 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 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.

DISABLE AVALARA ADDRESS VALIDATION

If necessary, you can disable Avalara's address validation in Configuration > Taxes > Tax Settings > Tax Service Settings. Deselect "Require valid address from tax service". If validation is disabled, addresses 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 > Site Settings. 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.

Taxable Regions

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

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 COUNTRIES

AUSTRALIA

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

Tax Region
Tax Type
Minimum Address Requirement

AU

GST

Country

ABN and ACN

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.

CANADA

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 Region
Tax Type
Minimum Address Requirement

CA

GST
GST/PST
GST/HST
GST/QST

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 Name
Tax Type

Alberta

GST

British Columbia*

GST/PST

Manitoba*

GST/PST

New Brunswick*

GST/HST

Newfoundland and Labrador*

GST/HST

Northwest Territories

GST

Nova Scotia*

GST/HST

Nunavut

GST

Ontario*

GST/HST

Prince Edward Island*

GST/HST

Quebec*

GST/QST

Saskatchewan*

GST/PST

Yukon

GST

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

EUROPE (NON-EU)

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:

Country
Tax Region
Tax Rate

Albania

AL

20%

Belarus

BY

20%

Bosnia and Herzegovina

BA

17%

Georgia

GE

18%

Iceland

IS

24%

Liechtenstein

LI

7.7%

Macedonia, The Former Yugoslav Republic of

MK

18%

Moldova

MD

20%

Norway

NO

25%

Russia

RU

18%

Serbia

RS

20%

Switzerland

CH

7.7%

Turkey

TR

18%

Ukraine

UA

20%

RUSSIA

Due to the January 1, 2017 rules to collect Russian VAT on cross-border sales of digital services, Russian VAT will not be applied to B2B invoices where the merchant's Site Settings country is not Russia. Business customers are identified by having a value in the VAT Number address field.

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.

ISRAEL

Enabling tax collection in Israel will apply 17% VAT to all taxable plan, add-on or adjustment line items for customers in Israel.

Tax Region
Tax Type
Minimum Address Requirement

IL

VAT

Country

NEW ZEALAND

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.

Tax Region
Tax Type
Minimum Address Requirement

NZ

GST

Country

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.

SOUTH AFRICA

Enabling tax collection in South Africa will apply 14% VAT to all taxable plan, add-on or adjustment line items for customers in South Africa.

Tax Region
Tax Type
Minimum Address Requirement

ZA

VAT

Country

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.

Taxable Plans and Adjustments

PLANS

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

How to enable a plan to collect tax

ADJUSTMENTS

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

How to create a charge with tax

TAX PRODUCT TYPE

Recurly's basic tax calculations through Avalara's AvaTax calculates 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 and use Avalara's 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 four 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.

Example

Given

  • 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

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.

IMMEDIATE 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 CREDIT 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 when you upgrade to connecting your own Avalara AvaTax 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 internal rate tables. Where as production mode will use Avalara for all final invoice tax calculations and will only use Recurly's internal rate tables 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 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 a future subscription activation or renewal.

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

FOR NEW SIGN-UPS AND PURCHASES

If Recurly cannot get a 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"

DISABLE TAX RESPONSE REQUIREMENT

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 tax response from tax service".

If you disable the tax response requirement, invoices will be created without tax when Avalara or Recurly's internal tax service is unresponsive. 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 a subscription and will keep retrying the activation or renewal every hour until a response is received from Avalara. While the renewal may happen an hour late, the underlying subscription dates will respect the original subscription billing cycle. We retry the activation and renewal to ensure that no invoice for a customer in a taxable location is created without a tax consideration. This functionality, unlike sign-ups and purchases, cannot be configured or changed.