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    

European Union VAT

Recurly supports VAT collection and VAT number validation for all 28 member states of the EU. Merchant selling digital products can choose to enable automated Location Validation for the 2015 digital rate changes.

EU Countries and Territories

EU VAT Countries

  • Austria (AT)
  • Belgium (BE)
  • Bulgaria (BG)
  • Croatia (HR)
  • Cyprus (CY)
  • Czech Republic (CZ)
  • Denmark (DK)
  • Estonia (EE)
  • Finland (FI)
  • France (FR)
  • Germany (DE)
  • Hungary (HU)
  • Ireland (IE)
  • Italy (IT)
  • Latvia (LV)
  • Lithuania (LT)
  • Luxembourg (LU)
  • Malta (MT)
  • Netherlands (NL)
  • Poland (PL)
  • Portugal (PT)
  • Romania (RO)
  • Slovakia (SK)
  • Slovenia (SI)
  • Spain (ES)
  • Sweden (SE)
  • United Kingdom (GB)

EU VAT Territories

Requires your own AvaTax account

These territories require VAT collection and are not currently supported by Recurly's basic taxes. If you have customers in these locations and need to collect VAT, contact Recurly support so we can track interest in these regions for our basic taxes. You can connect your own AvaTax account to Recurly to start collecting VAT in these territories now. Learn about AvaTax.


  • Monaco (MC)

United Kingdom

  • Isle of Man (IM)

EU Special VAT Rate Territories

Requires your own AvaTax account

These territories require special VAT rates and are not supported by Recurly's basic taxes. You can connect your own AvaTax account to Recurly to start collecting special VAT rates in these territories. Learn about AvaTax.


  • Azores
  • Madeira


  • several islands on the Aegean Sea


  • Corsica

EU Territories That Don't Require VAT

According to the European Commission, these EU territories do not require VAT collection and will not collect VAT in Recurly.

VAT may depend on the country code

Some territories have their own country codes. You can see the country code, if it exists, in parentheses next to the territory name below. For these territories with their own country code, if the territory's associated EU country code is used in the customer address, and you have EU VAT enabled, the customer will be charged VAT based on that EU country's rules.

To ensure VAT is not collected, you must either use the country code of the territory, or mark the account as tax exempt.

If the customer does enter the EU country and is charged VAT by mistake, you will need to:

  • Refund the invoice
  • Change the address country to the territory country code instead of the EU country code
  • Recreate the invoice using custom charges and credits on the account


  • Island of Helgoland
  • territory of Busingen


  • Ceuta (EA)
  • Melilla (EA)
  • Canary Islands (IC)


  • Guadelupe (GP)
  • Guyana (GY)
  • Martinique (MQ)
  • Réunion (RE)
  • Mayotte (YT)


  • Livigno
  • Campione d'Italia
  • Italian waters of Lake Lugano


  • Mount Athos


  • Jungholz
  • Mittelberg


  • territory of Greenland (GL)
  • territory of the Faroe Islands (FO)


  • Åland islands (AX)

United Kingdom

  • Channel Islands - Must be the code of either Jersey or Guernsey
    • Jersey (JE)
    • Guernsey (GG)
  • Gibraltar (GI)

Your Tax Identity

All merchants can use the EU VAT feature. It does not matter if your business is located in the EU or outside of the EU. Before you enable the EU VAT feature, make sure your tax identity is correct. All invoices will calculate tax based off of your company address found on the Site Settings page. While VAT is a country based rate, you must also provide your postal code for tax rate calculations.

Additionally, on the Site Setting page you can enter your VAT Number. This number will appear on all invoices and should match the country in our company address, unless you are located outside of the EU. We do not validate merchant VAT Numbers, so make sure your number is correct.

Who is Taxed

Who is taxed depends on your country location. If your Site Settings country is in the EU, VAT will be applied to any invoice with a customer country located in the EU, unless the customer identifies as a business by providing a VAT registration number.

If your Site Settings country is not in the EU, VAT will only be applied to invoices with a customer country located in a country where you are registered to collect VAT. See the VAT Registered Countries section below to learn how to configure the EU countries you are registered to collect VAT in.

In order to know who to tax, you must collect country from your customers. For most merchants, this will be the Billing Info Country field. If you have set your taxes to calculate on Account Info Address, this field will be the Account Info Country.

VAT Registered Countries

Recurly's EU VAT feature requires merchants to identify the EU countries where they are registered to collect VAT. You must select at least one country to enable the EU VAT feature. If you are located in the EU, you need to select the country you have as your Site Settings country as one of the "VAT Registered Countries", otherwise your VAT rates will be incorrect.

  • If your Site Settings country is in the EU, the VAT registered countries you select will affect the VAT rate. An EU customer in one of your VAT registered countries will see their own country rate applied to the invoice. An EU customer that is not in one of your VAT registered countries will see a rate depending on the Tax Type of the product. Digital products will show the customer's country rate, while physical products will show your Site Settings country rate. Learn more about rates here.
  • If your Site Settings country is not in the EU, the VAT registered countries you select will be the only countries where VAT is applied. VAT will always be applied at the customer's country rate.
  • If you are a Digital Services company and have registered through MOSS for all EU countries, you will need to select all the countries in the list.

EU VAT Registered Customers

If a customer provides a valid EU VAT registration number, they are identifying themselves as an EU business. If the customer is in the same country as your Site Settings country, VAT will be applied. If the customer is in a different country than your Site Settings country, VAT will not be applied. This is called a "Reverse Charge". In this scenario, no VAT line will show in the invoice table and a notes section called VAT Reverse Charge Notes will display on the invoice with a general statement of: "No VAT charged. Customer provided VAT registration number and may be responsible for VAT fees."

Merchants can edit the default message on the Tax Settings page, which is linked to in the top right corner of the Taxes page. Most merchants will want to update the note to specify specific legislation about reverse charges. This site level default note will appear on all reverse charge invoices. You can edit the notes for a specific reverse charge invoice before posting the invoice through your Recurly Admin or the API.

VAT Number Validation with VIES
To learn about Recurly's VAT number validation, please read our dedicated documentation.

Sample error responses for invalid VAT number

If you are planning on transitioning from sandbox mode to production mode, then it may be useful to know ahead of time the response Recurly will generate with invalid VAT numbers. Below is a sample XML error response that would occur when creating an account with an invalid VAT number:

Accept: application/xml
Content-Type: application/xml; charset=utf-8

  <error field="account.vat_number" symbol="invalid">is invalid</error>

Exempt Customers

The EU VAT feature allows you to set a customer's account as exempt. This can be set in your Recurly Admin under Account Info or through the API when creating an account. Exemption should be used when an account is exempt, but does not have a VAT Number. This may be a government or non-profit business. If the account is exempt, no VAT will be applied to the invoice. If you require special notes about the exemption, you can use one of the two notes sections on the invoice, "Terms and Conditions" or "Customer Notes". You will need to edit the custom notes at the time the invoice is created.

What to Tax: Configure Plans and Charges

The current EU VAT feature automatically taxes everything. The feature provides the option to turn off taxes for a plan or charge. When you enable the feature, all of your plans will automatically have taxes turned on. When you create a new plan or charge, the "Collect Sales Tax" box will be checked by default. If you issue a charge (adjustment) through the API, you will need to specify that the charge is not tax exempt on every call in order for taxes to be collected on that charge.

How to Tax: Identify Digital Services

Digital services like telecommunications, broadcasting and electronic services need to be identified as digital at the product level. This distinction will ensure that EU consumers are taxed properly at their country rate and not your own when it is a cross-border sale. Plans, add-ons, and one-time charges can be configured to specify a Tax Type of "Digital Product", "Physical Product", or "Unknown". All plans, add-ons, and charges are "Unknown" by default. Both "Unknown" and "Physical Product" will result in a Tangible Personal Property (TPP) distinction in Avalara when they calculate the tax. This field is called Tax Type in the Admin Console and tax_code in the API and Recurly.js.

To see Tax Type, first enable the plan to "Collect Tax". Change the Price per Billing Period Fee to "Digital Product"

To see Tax Type, first enable the plan to "Collect Tax". Change the Price per Billing Period Fee to "Digital Product"

Set the Tax Type for Add-Ons

Set the Tax Type for Add-Ons

If you are marking plans, add-ons or charges as a Digital Product, make sure you are also VAT registered in all 28 EU countries and have selected all countries on the EU VAT Configuration page. If you are not VAT registered in the EU country where the digital line item is being invoiced, the invoice will be blocked.

Understanding VAT Rates

Merchant's Site Settings country is in the EU and is selected as a VAT registered country:

Scenario VAT Rate Country
Customer is not in the EU No VAT
EU customer has a VAT number and is the same country as the merchant Merchant
EU customer has a VAT number and is in a different country than the merchant No VAT
Line item has Tax Type of "Digital Product" (2014)* Merchant
Line item has Tax Type of "Digital Product" (2015 and beyond)* Customer
Line item has Tax Type of "Unknown" or "Physical Product" and EU customer is in a VAT registered country Customer
Line item has Tax Type of "Unknown" or "Physical Product" and EU customer is NOT in a VAT registered country Merchant

Merchant's Site Settings country is NOT in the EU:

Scenario VAT Rate Country
Customer is not in the EU No VAT
EU customer is not in a VAT registered country No VAT
EU customer has a VAT number No VAT
EU customer is in a VAT registered country and line item has Tax Type of "Unknown", "Physical Product" or "Digital Product" Customer

When to Tax: Require Two Pieces of Location Evidence

If you are selling digital services to non-business customers in the EU, VAT regulation requires that you collect two pieces of non-conflicting evidence of what country the customer is located in. To require two pieces of location evidence from non-business customers, use Recurly's Tax Location Validation feature.

Enable Location Validation

  1. Go to Configuration > Taxes > click the "Tax Settings" button at the top right corner of the Taxes page.
  2. Scroll down and enable "VAT Location Validation" under the "European Union VAT Settings" section. Make sure you "Save Changes" at the bottom of the page.

As soon as VAT Location Validation is enabled, we will check all of your existing accounts in the EU with no VAT number and an active subscription. You will receive an email at your Billing Contact for each account that is currently invalid for VAT rules. Additionally, you can export the Accounts export and see a list of who is invalid under the "tax_location_valid" column. Look for the value "FALSE", meaning the account is invalid.

For each email you receive, or each account that is "FALSE" in the Accounts export, visit that account in Recurly to see the Activity event that shows what evidence the customer does have and contact the customer to gather more evidence in order to avoid their subscription cancelling at renewal. Save the new evidence for the invalid customer and confirm that their invalid account banner goes away. You will see a successful Activity on the account as well.

Learn more about our Tax Location Validation.

Country Specific Invoice Sequences

Recurly uses one sequence of invoice numbers for your site by default. This follows the European Commission's invoice sequencing rules. Some member states require a separate sequence of numbers just for that country. We have built a feature for this requirement that we call Country Invoice Sequencing. This feature allows merchants to create a different sequence for each member state in the EU. Once enabled, all new invoices in the EU will have an invoice number that increments that country's sequence. Each sequence starts with 1000 and is prefixed by the two letter country code (Ex. FR1000 for France). Country specific sequences are only for the 28 member states of the EU. Invoices with customers in non-EU countries will increment the site-level sequence.

Enable Country Invoice Sequencing

  1. Go to Configuration > Taxes > click the "Tax Settings" button at the top right corner of the Taxes page.
  2. Scroll down and enable "Country Invoice Sequencing" under the "European Union VAT Settings" section. Make sure you "Save Changes" at the bottom of the page.

Invoice Localization

Recurly invoices viewed or downloaded from Hosted Account Management pages are translated into one of the twelve languages Recurly supports, if the customer's browser settings are set to that language. Recurly email notifications to customers are only in English and do not support translations. The twelve supported languages for hosted pages are:

  1. English
  2. Danish
  3. German
  4. Spanish
  5. French
  6. Hindi
  7. Japanese
  8. Dutch
  9. Portugese
  10. Russian
  11. Turkish
  12. Chinese

Not Doing: VAT Currency Conversion

EU VAT rules require the VAT amount on an invoice to be displayed in the local currency of the customer. Recurly does not provide this feature and does not have support in the EU VAT tool.


Merchants can either generate invoices themselves, or programmatically enter VAT currency conversion information into one of the two notes sections on an invoice before the invoice is created. These are "Customer Notes" and "Terms and Conditions".

This workaround will require editing the notes before each subscription renewal. You will need to store subscription renewals on your side and trigger the Update Subscription API call before the renewal.

Suggested Notes Editing Flow

  • Preview the subscription or adjustment invoice via the API and look for <tax_type>vat</tax_type>
  • If <tax_type>vat</tax_type>, grab the <tax_in_cents>, <currency>, and <country> under <address>
  • Run your own currency conversion
  • Post the invoice or create the subscription via the API and store your currency conversion notes in either <terms_and_conditions> or <customer_notes> in the call
  • If this is a subscription, you will need to store the renewal date or query for renewals on your side and then trigger an Update Subscription Notes call with the notes before the renewal creates the invoice.

Not Doing: Multiple Merchant Addresses

Recurly currently stores one merchant address, collected on the Site Settings page. The address is used for the merchant's address on all invoices and tax calculations. If you require multiple merchant addresses for your invoices or tax calculations, we are unable to support you at this time.

How to Enable Tax Collection

In-the-Box Taxes

  1. Make sure your Site Settings address has a country and a postal code.
  2. In the Admin Console, go to Configuration > Taxes and click "Configure" next to "European Union (VAT)" at the bottom or the page.
  1. On the next page, select "Enabled" and you will see the country list appear. You must select at least one country. EU merchants must include the country that matches your Site Settings country. Non-EU merchants selling digital services must enabled all countries, otherwise sales will be blocked in the not enabled countries.
  1. Once you click "Save Changes", you will see a modal making you aware that we use Avalara for tax calculation and asking you to agree to our terms.
  2. After you enable EU VAT, you will see the section marked green on the Taxes page. You can always go back to the Configure page and disable specific countries or the entire feature if you need to make changes.
  1. Now go to the Configuration > Plans page and configure each plan to be taxable and define the each plan and add-on's Tax Type as either a "Physical Product" or a "Digital Product". The default is "Unknown", which follows basic physical good tax rules.

Avalara AvaTax Pro

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.

Connect your AvaTax Pro Account

The first step is to connect your AvaTax Pro account by providing your credentials. Please read our AvaTax Pro support article for details on how to configure your account.

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.


If you are using Recurly.js to display tax details during signup, you will need to be using at least Recurly.js v3 in order to use the EU VAT feature. If you need to update your Recurly.js version for tax support, we recommend updating to the latest Recurly.js v4. Our deprecated Recurly.js v2 will not work for tax previews once you enable the feature. Merchants selling digital services will need to update their tax previews to specify a tax_code of "digital" in order to preview the correct VAT amount. See an example here.

If you would like to display the country code of the VAT rate in your tax previews, you can use the "tax_region" attribute. We do not currently have tax_rate in Recurly.js, but we have documented a way to find the rate in Github Issue #163. Learn more about our Recurly.js.


If you are using Recurly.js to accept PayPal sign-ups, you will need to adjust your calls to make sure you store the customer country before the subscription is created. PayPal tokens will not store an address in the Billing Info, you will need to store that information. Normally you would use Recurly.js to get a PayPal token and then store that in the Billing Info in the same API call that creates the subscription. For VAT, you will need to create the Billing Info and then update it with the country before the subscription is created. Here is our suggested flow:

  1. Include country in your checkout form.
  2. Preview the pricing to the customer with Recurly.js. The pricing will have the correct tax because the country from the form is being considered in the preview.
  3. When the customer confirms they want to use PayPal to make the purchase, use Recurly.js to get a PayPal token.
  4. Then use the API to create the account and billing info.
  5. Use the API to update the billing info again with the address you collected in the Recurly.js form. In this call, do not include the token, just the new address information.
  6. Now create the subscription using the Create Subscription API call.
  7. If the sign-up fails, you will still have an account for that person in Recurly. You can leave it or you can use the API to Close the Account.

If you are using Recurly's Hosted Payment Pages to accept PayPal sign-ups, we do receive a country from PayPal with the billing agreement and that country is stored in the Billing Info before the subscription is created.

Frequently Asked Questions (FAQ)

Does the EU VAT feature provide an option for "tax included" pricing?

No, we do not currently offer "tax included" pricing. All VAT amounts are added to the purchase amount (Subtotal). If you would like a tax included option, please let us know by contacting Recurly Support.

What happens if I don't upgrade Recurly.js to at least v3 and I enable the EU VAT feature?

If you are using Recurly.js v2 and enable the EU VAT feature, your VAT preview amounts may be inaccurate and not match the resulting invoices. The actual invoices will not be affected and will be accurate.

What if I am not collecting billing or shipping info at checkout?

If you are not collecting a country at check out and storing that in either Billing Info or Account Info, depending on your tax address settings, we cannot calculate tax. It is impossible to calculate tax without knowing where the customer is. Luckily, VAT is a country level tax and only requires country in order to calculate accurate rates. We do not recommend storing IP address in Billing Info as that is not the most accurate indication of location. A customer could be traveling or doing IP spoofing. We do use IP address for location evidence for digital services, but that is as a secondary piece of evidence. The primary address evidence is always the billing address or the account address (shipping address).

What if I am selling digital services in the EU, but am not registered in all countries

By not registering in an EU country, you are essentially agreeing to not sell digital services there. Recurly will block digital sales to countries where you are not VAT registered, unless the customer provides a valid VAT number.

Does Recurly provide VAT registration?

Recurly does not provide VAT registration directly, but our tax partner, Avalara, does provide VAT registration and can help you with MOSS and tax filing and reporting. These services are a part of the AvaTax Pro feature where you connect your own AvaTax account. To talk to our partners at Avalara, email

We are a digital services company outside of the EU, do we still need to collect VAT?

Yes, if you are selling to any consumers (Not VAT registered). All digital services merchants selling into the EU need to collect VAT on sales to consumers at the rate of the customer's country. There is no sales threshold. Even just one sale requires VAT collection and registration. We recommend every merchant collecting taxes or considering collection speak with a tax advisor. If you do not have one, we can introduce you to the tax experts at Avalara for a consultation. For an introduction to Avalara, please email

My customers are always VAT registered businesses, is there a way to make sure cross-border sales don't charge VAT if the customer doesn't provide a VAT number at the time of purchase?

No, if the customer is in an EU country, you have enabled EU taxes, and the customer does not provide a valid VAT number, Recurly will automatically collect VAT on top of their purchase. If you want to avoid all VAT collection outside of your own country, we recommend your require a VAT number from all EU customers.