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    

Avalara AvaTax Pro

Avalara and Recurly have partnered to provide accurate rate calculation out-of-the-box. Companies ready to take tax compliance to the next level can upgrade to Avalara AvaTax for Recurly and leverage Avalara’s powerful sales tax engine right within their Recurly site.

Avalara AvaTax dynamically delivers instantaneous sales tax decisions based on precise geolocation in more than 12,000 taxing jurisdictions in the U.S. AvaTax automatically assigns hundreds of thousands of taxability rules and the latest jurisdiction boundaries to deliver the right rate and tax calculation.

If you don't have an AvaTax account, sign up here. Find out more about Avalara AvaTax.

Go Live with Avalara Checklist

  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 Avalara's APIs for the tax preview portion.
  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.

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:

  1. Make sure that your site is in production mode. You can test in sandbox mode but are limited to Avalara's development environment.
  2. Select the Taxes section
    in the left-hand navigation.
  3. Click "Learn More" on the Avalara banner on the right-side of the page in the orange highlighted box.
  4. Have your Avalara Account Number, Company Code and License Key ready and enter
    those values on the form.
  5. 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.
  6. Select the Avalara environment, Development or Production, you want use. When you're processing
    real transactions, you should be sending transactions to Production.
  7. Click Save Changes.
  8. Before proceeding test the connection by clicking the Test Configuration button before continuing on.

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.

  1. Select "Collect Tax" under Plan Details. This will make all plan items taxable: setup fee, plan fee, add-on fees.
  2. Enabling tax for the plan will expose a Tax Code field where you can place your Avalara tax code for the plan level fee.
  3. If you have a setup fee, it will use the same tax code as the plan fee.
  4. Each add-on can have it's own tax code as well.
  5. 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 Pro customers in the API in the Preview Subscription, Preview Subscription Change, and Preview Invoice endpoints. Tax previews for Avalara AvaTax Pro are not yet supported by Recurly.js 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/.

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 Pro 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 Pro 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 Pro 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 Pro merchants automatically have VAT Number validation turned on and will see new Reverse Charge notes on invoices with customer VAT Numbers.

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

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 if your Avalara account becomes "Inactive" for any reason. If your Avalara credentials stored in Recurly become invalid, Recurly will send your Technical Contact an email letting them know the credentials are invalid and taxes are currently not being applied. If you receive this email, you should enter your updated Avalara credentials in Recurly, or contact Avalara to learn why your credentials are no longer valid.

While your Avalara credentials are invalid, Recurly will allow invoices to be created without a tax consideration. This means invoices will not be blocked and will go through without tax.

Avalara AvaTax Pro

Avalara and Recurly have partnered to provide accurate rate calculation out-of-the-box. Companies ready to take tax compliance to the next level can upgrade to Avalara AvaTax for Recurly and leverage Avalara’s powerful sales tax engine right within their Recurly site.

Avalara AvaTax dynamically delivers instantaneous sales tax decisions based on precise geolocation in more than 12,000 taxing jurisdictions in the U.S. AvaTax automatically assigns hundreds of thousands of taxability rules and the latest jurisdiction boundaries to deliver the right rate and tax calculation.

If you don't have an AvaTax account, sign up here. Find out more about Avalara AvaTax.