Avalara AvaTax

🚧
International Tax Collection
If you will be using your Avalara account to tax customers outside of the U.S. or Canada, note that Avalara does not support the logic for reverse charges in the following cases:

Non-Russian merchant to Russian customer with SRN/SRNIE

Non-Australian merchant to Australian customer with ABN that is active and registered for GST

Non-New Zealand merchant to New Zealand customer with GST Number

Non-Mexican merchant to Mexican customer with VAT number

If you require the above missing reverse charge cases, please use Recurly's out of the box taxes or talk to your Avalara representative to identify when Avalara will be adding this logic.

Go Live with Avalara Checklist

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

Connect Your Avalara AvaTax Account

Once you have an Avalara AvaTax account, you can connect it to Recurly. We recommend connecting your AvaTax account to Recurly before you enable your tax jurisdictions in Avalara in order to allow time to configure your Recurly account for taxes before you begin collecting taxes in those jurisdictions.

To enable Avalara AvaTax for your Recurly site, follow the steps below:

Make sure that your site is in production mode. You can test in sandbox mode but are limited to Avalara's development environment.
Select the Taxes section in the left-hand navigation.
Click "Sign in with Avalara" in the right sidebar of the page.
Have your Avalara Account Number, Company Code and License Key ready and enter those values on the form.
Determine whether you want Recurly to set your tax records to committed in Avalara
when an invoice is marked as paid in Recurly. The default is set to uncommitted.
If you would like to commit invoices to Avalara, determine whether you want to follow accrual basis or cash basis accounting for reporting sales tax in Avalara. The default is set to accrual basis in line with GAAP compliance.
Select the Avalara environment - Development or Production - you want to use. When you're processing real transactions, you should be sending transactions to Production.
Select if you want to send $0 invoices to Avalara. Invoices created at the start of a trial are $0 and will have not have any taxes applied. To avoid Avalara charging for these invoices, don't send $0 invoices.
Select which Account Identifier to send to Avalara as the Customer Code. Recurly Account Codes are typically set by you and are used by default. Recurly Account IDs are system generated IDs Recurly sets. If you are storing any potential PII in Recurly's Account Code (e.g. email address), you should select Account ID.
Click Save Changes.
Before proceeding, test the connection by clicking the Test Configuration button to ensure the connection is made properly.

Configure Plans and Add-ons

Recurly will only send Avalara line items that you say are taxable. Configure the plans and add-ons you want to tax under Configuration > Subscription Plans > Select a plan > Click Edit.

Select "Collect Tax" under Plan Details. This will make all plan items taxable: setup fee, plan fee, add-on fees.
Enabling tax for the plan will expose a Tax Code field where you can place your Avalara tax code for the plan level fee.
If you have a setup fee, it will use the same tax code as the plan fee.
Each add-on can have it's own tax code as well.
Save your plan. Any customer in one of your tax jurisdictions that purchases this plan will now be taxed.

Taxes are always on top of the line item's price. This means that new customers will pay your pricing plus tax and current customers in your taxing jurisdictions will see their next renewal invoice with tax added on top of their normal fees.

Tax Jurisdictions in Avalara

Where you are going to tax is determined in your Avalara AvaTax account. Configure the countries, states/provinces, and any lower level jurisdictions in your Avalara AvaTax account. When you enable a jurisdiction, Avalara will set a beginning date and end date. This reflects the time period where customers in that jurisdiction should be considered for taxes.

We recommend not enabling your production tax jurisdictions until you have connected your account to Recurly and have configured Recurly site accordingly.

Avalara jurisdiction dates do not have a time stamp. This means that if you turn a jurisdiction on mid-day, any untaxed invoices in that jurisdiction from earlier in the day may run into problems if they need to be refunded. When you attempt a refund, Avalara will try to calculate taxes and Recurly will throw an error because the resulting invoice is attempting to be more than the original invoice, which we don't allow. In this special case, we suggest setting your jurisdiction beginning date one day ahead, refunding the invoice, and then setting the date back to what it was. You can submit a feature request for jurisdiction time stamps to your Avalara representative or the Avalara support team.

Tax Previews

Recurly supports tax previews for Avalara AvaTax customers in the API in the Preview Subscription, Preview Subscription Change, Preview Purchase, and Preview Invoice endpoints. Using those calls, Recurly will query Avalara AvaTax directly for the tax information and return it in the preview. Tax previews for Avalara AvaTax are not yet supported by Recurly.js, the Recurly Admin Console, or the Hosted Payment Pages.

Tax Exempt Customers

Recurly allows you to mark specific customer accounts as tax exempt, removing the account from any taxes. To mark an account as tax exempt, edit the Account Information on the account and select an Entity Use Code. Entity Use Code is an Avalara field. We suggest talking with your Avalara representative about which Entity Use Codes you should use.

We do not currently have a way for a customer to note that they are tax exempt at purchase. We recommend having a message a purchase that any tax exempt customers should contact you first. You will need to make an account for the customer and mark them with an Entity Use Code. The customer can then sign up with the same account email address. They will likely still see a tax preview, but will not be charged tax.

Avalara has a tool for managing exemption certificates called Avalara CertCapture. Recurly doesn't have an integration with Avalara CertCapture, but we are collecting requests for this functionality. If you would be interested in using Avalara CertCapture with Recurly, please submit a support ticket with this request at https://support.recurly.com/.

Tax Inclusive Pricing

Tax inclusive pricing is available using Avalara. Please see the Tax Inclusive Pricing page for more information.

Test Your Integration

You can test your integration on a sandbox site. Configure your sandbox site following all of the instructions above. When you enter your Avalara AvaTax credentials, you will use the development environment option.

You will not be able to commit paid invoices to Avalara in sandbox mode.
If you test on the same site that you are going to move to production, make sure you switch the environment to production on your Avalara AvaTax credentials page after you move your Recurly site to production mode.

IMPORTANT: We send the invoice number to your Avalara AvaTax account. If the invoice number already exists in your AvaTax "company", the invoice will be rejected and no taxes will be applied. This may happen if you use multiple sites with the same Avalara AvaTax account and company configured, or if you move to production in Recurly, which starts your invoice numbering over again. If this error occurs, you will see this error message:

A duplicate tax document exists. If in Sandbox mode, please clear test data

If you need to use the same Avalara AvaTax account with multiple Recurly sites, you will need to setup a separate company for each Recurly site in your AvaTax account and then configure the specific company code in your Avalara credentials in each Recurly site.

How Recurly Fields Map To Avalara

This section details which fields Recurly will send to Avalara with each invoice that is created.

Accounts

Accounts can be referenced on your Avalara tax documents using these fields.

Account Code

The Account Code that you use when creating an account in Recurly is mapped to the Customer Code field in your Avalara records.
####Entity Use Code
The Entity Use Code is an optional field that you can set in Recurly in order to help you manage your customer’s exempt status. It's mapped to the same field, Entity Use Code, in Avalara.
####Address Info
For automatic invoices, your customer's Billing Info address is passed to Avalara. For manual invoices, the Account Info address is passed to Avalara. If you have your Tax Settings set to "Use Account Information Address", this address will always be sent to Avalara, even for automatic invoices.

Plans

Plans can be referenced on your Avalara tax documents using these fields. Note that a
plan's setup fee also inherits these values in your Avalara tax records.

Plan Name

The Plan Name is only used in Recurly and is not passed to Avalara.
####Plan Code
The Plan Code is only used in Recurly and is not passed to Avalara.
####Plan Description
The Plan Description is passed to Avalara as the Description for line items when invoices are created.
####Accounting Code
The Accounting Code is passed to Avalara as the Item Code.
####Tax Code
The Tax Code is passed to Avalara and is used to apply specific taxability rules for products and/or regions.
####Editable Quantity
Editable Quantity is not passed to Avalara, but see the Invoices section for quantities on tax records.
####Pricing Information
The Pricing Information, including the Currency, is passed on to Avalara for your plan.

Add-Ons

Add-Ons can be referenced on your Avalara tax documents using these fields.

Name

The Name is passed to Avalara as part of the Description for line items when invoices are created.
####Add-On Code
The Add-On Code is only used in Recurly and is not passed to Avalara.
####Accounting Code
The Accounting Code is passed to Avalara as the Item Code.
####Tax Code
The Tax Code is passed to Avalara and is used to apply specific taxability rules for products and/or regions.
####Price
The Price, including the Currency, is passed on to Avalara for your plan.
####Editable Quantity
Editable Quantity is not passed to Avalara, but see the Invoices section for quantities on tax records.

Invoices

Invoice details can be referenced on your Avalara tax documents using these fields.

Invoice Number

The Invoice Number is passed to Avalara as the Document Code.
####Invoice Date
The Invoice Date is passed to Avalara as the Document Date.
####Line Items
The line item details on an invoice are passed to Avalara.
####Invoice Amounts
The total taxable and non-taxable amounts are passed to Avalara.

Return and Void Scenarios

Recurly also fully supports returns and voids for tax documents from your Recurly site to
your Avalara Avatax account.

Return Document for Refunds

When you process a refund from Recurly, Recurly will post a new tax transaction record in your Avalara account. This will be reflected in Avalara as a Return Invoice and will reference the line item details and invoice summary information.

The fields listed for the invoices above are the same with the addition of 1) the original
invoice number being passed as the Reference Code in Avalara and 2) the original invoice date being pass as the Tax Override Date on the new refund invoice.

Void a Tax Document

Voids can be applied in your Avalara AvaTax account for either uncommitted or committed tax records when initiated from Recurly.

For automatic invoices, an invoice is voided in your Avalara AvaTax account when a payment fails and cannot be recovered through dunning or is set to stop collecting. Subsequently, the invoice state is marked as failed in Recurly as well.
For manual invoices, an invoice is voided in Avalara AvaTax account when you manually set to be marked as failed. Subsequently, the invoice state is marked as failed in Recurly as well.

European Union VAT

Merchants using their own AvaTax account with Recurly can stay compliant with EU VAT requirements using Recurly's additional EU VAT features like invoice messaging, country invoice sequencing, and location validation for digital services customers.

Define a Digital Service

If you have a plan, add-on or charge that is a Digital Service, you will need to use Avalara's Tax Codes to make that distinction. When you have your AvaTax account connected, on the Edit Plan page, you will see the plan Tax Code box below the "Collect Sales Tax" checkbox. Additional Tax Code fields are found next to the add-ons on that page and on the Create a Charge page.

Talk with our Avalara representative to figure out what the appropriate tax codes are for your products in order to achieve the EU VAT Digital Services distinction. A basic Digital Services tax code that will work is D0000000.

Other EU VAT Features

AvaTax merchants have access to Location Validation for Digital Services evidence requirements and Country Invoice Sequencing if you require a separate invoice sequence for each EU country. These features are both found on the "Tax Settings" page, which is accessible from the top right corner of the Taxes page. Additionally, AvaTax merchants automatically have VAT Number validation turned on and will see new Reverse Charge notes on invoices with customer VAT Numbers.

Canadian Tax Rates

Canada has certain regulations that require country and state level taxes to be broken out on the final customer invoice. Recurly will display the different tax rates on their own line for customers to see the tax breakdown.

Handling Avalara Downtime

When an invoice is created on a site with Avalara AvaTax credentials, 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"

Since all invoices are sent to Avalara, this sign-up or purchase block also affects invoices for customers in locations where you do not collect tax, tax exempt customers, or tax exempt line items.

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, initial purchase 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.

If the Avalara tax service returns an error during a renewal, though, the renewal will be processed without tax.

Invalid Avalara Credentials

Recurly validates your Avalara credentials whenever they are added or edited to keep you from saving invalid credentials. Your Avalara credentials will become invalid in Recurly if your Avalara account becomes "Inactive", meaning your development or production Avalara account expired, or if Avalara is having authentication service issues.

Email Notification

When your credentials are determined to be invalid, Recurly will send an email to your Technical Contact. If you have not specified a Technical Contact, the email will go to your Billing Contact. If you have not specified a Billing Contact, the email will go to the first user on the account with Admin user rights. This email will only be sent once at the time the credentials become invalid.

Invoicing

While your credentials are invalid, the mode of your site will determine invoicing.

Production Mode

If your site is in production mode, Recurly will continue to send invoices to your Avalara account. By default, new sign-ups and purchases will be blocked due to the authentication error Avalara returns. If you know your credentials are correct and you suspect that Avalara is having authentication issues, you can disable the block on new sign-ups and purchases and allow those invoices to go through without tax until Recurly gets a successful response from Avalara. To disable the block, go to Configuration > Taxes > Tax Settings > deselect "Require tax response from tax service" and save the page. Learn more about this option.

Whether you block or don't block new sign-ups and purchases due to an error, as soon as Recurly gets a successful response from Avalara on an invoice, Recurly will reset your Avalara credentials to be valid again. Note that when credentials are invalid, renewals will always go through and generate an invoice without tax. Recurly will not stall the renewal and retry. Recurly does not retry the subscription because if the Avalara account has truly expired, which is the primary scenario, it would stall subscription renewals across your site for potentially a long amount of time.

Sandbox Mode

If your site is in sandbox mode, meaning you are testing Avalara, Recurly will ignore your credentials and stop sending requests to Avalara when an invoice is created. This means each invoice will not have tax until you fix your credentials.

🚧International Tax Collection