How do I go live with Avalara AvaTax?

Going live with Avalara AvaTax is simple:

  1. Confirm your Site Settings company address is filled out and correct.
  2. Decide which customer address you want to tax, billing or account.
  3. Update your purchase form to require at least the minimum address fields needed for your tax regions.
  4. Confirm the current customer addresses you are going to tax are correct and include a country.
  5. Enter your Avalara AvaTax credentials on your production site before you enable the tax jurisdictions in Avalara.
  6. Configure your plans and add-ons with the correct taxability and tax codes.
  7. Update any purchase or subscription change previews to use Recurly's APIs for the tax preview portion, not Recurly.js.
  8. Mark any tax exempt current customers with an Entity Use Code in their Account Info.
  9. Test your integration on a sandbox site.
  10. Go live by turning on your tax jurisdictions in Avalara.



Merchant Tax Address

In order to calculate taxes, Avalara needs to know the merchant address for each invoice. This is called the "Origin" address in Avalara. Recurly uses the Site Settings company address on each invoice, so that is the Origin address we send to Avalara. In order for the Avalara integration to work, you must meet these criteria in your Recurly Site Settings company address:

  • Have at least a country and postal code
  • The address must match your Organization's "Company Address Settings" in Avalara



Customer Tax Address

The customer address is very important in taxes. If we don't know where the customer is located, we can't calculate taxes with Avalara.

Which Address To Tax

You have the option of calculating taxes based on Billing address or Account address. Many merchants collect a physical address and store this in the Account Information address. By default, Recurly will tax the Billing address for automatic transactions and the Account address for manual invoices.

To switch your tax address to the Account address, go to Configuration > Taxes > Tax Settings and enable "Use Account Information Address for all Invoices". Once selected, all invoices will use the Account Information address as the customer address. If an Account address does not exist for a customer, we will default back to the Billing address.

Which Address Fields to Require

It is always best to collect the full customer address to ensure the most accurate tax calculations, but we know that asking more information from customers can be a barrier to purchases. We suggest talking with Avalara about the minimum address requirements needed for your tax jurisdictions.

Recurly will require a country at a minimum in order to calculate taxes, even if Avalara is able to calculate the tax without the country. Once you enable your Avalara AvaTax account, country will automatically be required in the Billing address for all new signups. The Account address will not require country automatically, but is needed if you are going to tax based on Account address, so make sure you are storing the customer's country.

If a renewal receives tax from Avalara but does not have a customer country in Recurly, Recurly will throw a silent error and the renewal will be stuck until a country is added. There isn't an easy way to know which subscriptions are blocked due to lack of country, so we strongly suggest you do an address audit and update all addresses with a country before turning on taxes.

Avalara Address Validation

All invoices that receive tax will need a customer country. If the invoice does not have a customer country, the invoice will be blocked or the subscription will be queued and won't renew until a country is added. Please do an audit of all customer addresses before you start taxing and make sure all addresses or those you can tell are in taxable regions have a country included.

By default, our integration with Avalara AvaTax will validate all customer addresses. If a customer address is invalid, an error will be returned and the purchase will be blocked. Here are the possible error messages Recurly will return in the API and on the Hosted Pages:

The address provided is invalid, could not determine taxing jurisdictions
The state/province provided is invalid, could not apply tax

Renewals will not be blocked if an invalid address error occurs, but the resulting invoice will be rejected by Avalara and will not be considered for tax calculation. We do not block renewals in order to limit disruption with your current customers. There isn't an easy way to know which accounts had invalid addresses and did not receive tax, so we strongly suggest you do an address audit and update addresses before turning on taxes.

You can disable Avalara address validation in your Tax Settings under Configuration > Taxes > Tax Settings. Deselect the checkbox next to "Use Avalara's address validation" and save your settings. Disabling address validation will allow purchases with invalid addresses to go through in Recurly, but the invoice will be rejected by Avalara and will not be considered for tax calculation.