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    

EU VAT Number Validation

Recurly provides validation for European Union VAT numbers to keep merchants collecting VAT compliant in their B2B customer interactions.

How VAT Numbers Affect VAT Collection

VAT numbers are business tax registration numbers in countries that collect VAT (value-added tax). All 28 member states of the EU fall under one coordinated VAT system. EU businesses with a VAT number only pay VAT on purchases within their country. If an EU business makes a purchase from a different EU country, the business does not pay VAT on the transaction and instead delays VAT payment to their own tax filing in their own country. Due to this exemption at time of purchase rule, it is important that merchants validate whether a VAT number is real before issuing an invoice without VAT.

Validation Through VIES

Recurly allows you to collect a VAT number from any country, but only VAT numbers accompanied by an EU country will be validated. Recurly is integrated with the European Commission's VAT Information Exchange System (VIES) for validating EU VAT numbers. This is the only means of validating a VAT number. All other services and tools that do VAT number validation are using the VIES system. It is not possible to access the individual country VAT number databases directly. You can access the VIES website here: http://ec.europa.eu/taxation_customs/vies/.

VIES VAT number validation is a separate feature from Recurly's EU VAT collection and is on by default for sites in production mode. The VAT number validation response (valid/invalid) is stored in Recurly, along with the date/time of the validation response, but Recurly does not currently capture or store the VIES consultation number (also called request identifier) for these responses that would tie them back to the VIES system.

When VAT Numbers are Validated

VAT numbers are validated whenever a VAT number is added or updated to an account, at each billing event, or if an invoice is created more than six months from the last time the VAT number was validated. Here are the validation points:

  • Adding or editing Billing Information
  • Adding or editing Account Information
  • Creating or renewing Subscriptions
  • Creating one-time charges

Invalid VAT Numbers

A VAT number is invalid if we get a response from VIES explicitly saying the number is invalid, which means the number is not in their database. If a VAT number is invalid, we will not save it on the customer's account and will block any sign-up attempts with that invalid VAT number. We will not revalidate an invalid VAT number for 1 hour, so a customer attempting a sign-up with an already invalid VAT number will need to wait an hour before making another attempt. This may happen if your customer was recently issued their VAT number and the VIES database is not yet up to date.

If a VAT number becomes invalid while it's already on an account, the VAT number will remain on the account, but subscription renewals will go through with VAT applied.

If you have a customer claiming their VAT number is correct and VIES is showing that it is invalid, please consult the European Commission's FAQ question #13 on how the customer can fix the official record of their VAT number. http://ec.europa.eu/taxation_customs/vies/faq.html

VIES Downtime and Country Maintenance Windows

VIES is a validation endpoint that aggregates the 28 different EU country databases. Some of the 28 countries have regular downtime for maintenance. Unfortunately, VAT numbers for those countries cannot be validated at those times. You can see their maintenance windows here: http://ec.europa.eu/taxation_customs/vies/help.html

If we are unable to determine the validity of a VAT number, we will not save it on the customer's account and will block any sign-up attempts. We will re-validate a VAT number at subscription renewal if the VAT number has not been validated for six months. If the re-validation comes back without a valid or invalid response, meaning VIES or the individual country is down, we will fallback to the last validation status of the VAT number and will let the subscription renewal go through without VAT applied if the last status was valid, or VAT applied if the last status was invalid.

You can view the status of each state's VIES validator at http://ec.europa.eu/taxation_customs/vies/technicalInformation.html. Recurly uses the VIES SOAP API, which is represented in the right column, titled "Ws Access Status".

Disable VAT Number Validation

Please contact Recurly support if you'd like to disable VAT number validation on your Recurly site.

Test Validation

VAT numbers are not validated in sandbox mode in order to allow merchants to test what a real VAT number would do. If you would like to simulate an invalid VAT number, you can use the number 000000000 with any EU country.

Sample Invalid VAT Number Error

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:

Request


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

<account>
  <account_code>1</account_code>
  <email>[email protected]</email>
  <first_name>verena</first_name>
  <last_name>example</last_name>
  <vat_number>INVALID_VAT_1234</vat_number>
  <address>
    <zip>28070</zip>
    <country>ES</country>
  </address>
</account>
Response
<errors>
  <error field="account.vat_number" symbol="invalid">is invalid</error>
</errors>

Updated 3 months ago

EU VAT Number Validation


Recurly provides validation for European Union VAT numbers to keep merchants collecting VAT compliant in their B2B customer interactions.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.