Vatstack has been all about validating your customer’s VAT numbers. It displayed all relevant data fetched over the HTTP GET method, and that’s been about it. It’s been serving its purpose in most cases, but its weaknesses emerge especially when temporary downtimes of government services completely block us from proceeding with a customer’s checkout process.

This was just one of several other problems. The previous version of Vatstack was unable to do deliver a solution for these problems:

  1. Consultation numbers were not obtained on behalf of you which would serve as an official piece of evidence during audit.
  2. Records of past VAT number validations were not saved for future retrieval.
  3. There was no mechanism to send validation requests to the API for asynchronous processing, for example during downtime periods.
  4. Succeeded VAT number validation requests did not notify the originating source for further evaluation.

All of the above had us completely re-think the way we’ll validate VAT numbers going forward. We took all the ideas — collected from existing customers and potential customers — to the drawing board and sketched out what an ideal VAT validation feature should be capable of.

Allow us to introduce you to the new validations endpoint by addressing each of the above points.

The New Validations Endpoint in Detail

To help you get a better understanding of what we’ve improved, let’s take a look at the validation process.

You start by performing a POST request to our API in order to create a validation object. Under normal circumstances, you’ll immediately receive a status code 201 Created response and can determine whether your customer’s VAT number is registered or not. Look for the valid and valid_format booleans.

{
  "id": "5d1ded3128ca7a842aaf5ed4",
  "company_address": "3RD FLOOR, GORDON HOUSE, BARROW STREET, DUBLIN 4",
  "company_name": "GOOGLE IRELAND LIMITED",
  "consultation_number": "WAPIAAAAW21qsOHW",
  "country_code": "IE",
  "query": "IE6388047V",
  "valid": true,
  "valid_format": true,
  "vat_number": "6388047V",
  "requested": "2019-07-04T00:00:00.000Z",
  "created": "2019-07-04T12:12:33.322Z",
  "updated": "2019-07-04T12:12:33.322Z"
}

1. Consultation Numbers Obtained as Evidence

Every response includes a consultation number given by VIES. The consultation number of a request is a unique reference identifier and is an official piece of evidence used to show to tax administrations of a member state that you have rightfully validated a given VAT number on a given date.

Vatstack stores the consultation_number and the requested date in the validation object which you can review for future reference. To enable this feature, add your VAT number to your account settings. Note that evidence collection is only available for paid subscription plans.

2. Retrieve Historical Validation Records

Record-keeping can be especially useful for tax-filing purposes and if you are faced with an audit. It also serves as a single point of truth for traceability of tax treatment.

If you validate all your customers’ VAT numbers on a regular interval, you will know exactly at which point onward you have to cancel the reverse-charge mechanism for affected customers and start charting VAT. When a customer’s VAT number expires, you must either ask for a new one or treat the customer like a consumer by charging VAT at their local rate.

All VAT number validation requests (aside from the INVALID_INPUT ones) include a unique identifier id and are recorded for future retrieval. They are listed in your dashboard or can be fetched programmatically via API. You can also query by the VAT number by passing a query field in the URI. Find more details in the API documentation.

Fetching records from your validation history won’t count towards your monthly validation requests.

3. Handle Downtimes of Government Services

Government service downtimes happen regularly but will be a less blocking issue from now on. Validation requests are gracefully accepted and enter a schedule for automated re-validation.

You’ll get a status code 202 Accepted with an attached error code MS_UNAVAILABLE or SERVICE_UNAVAILABLE, meaning that Vatstack will continue to process your validation request asynchronously in the background.

The valid boolean will be null in this case because either true or false would be misleading.

{
  "id": "5d9f548b5b407ab2b9d12623",
  "code": "MS_UNAVAILABLE",
  "query": "IE6388047V",
  "valid": null,
  "valid_format": true,
  "created": "2019-10-10T15:55:55.661Z",
  "updated": "2019-10-10T15:55:55.661Z"
}

At the moment, we will re-try to obtain a result every 2 hours but aim to optimize the schedule.

Meanwhile, you can fall back to your historical records. If there is a record, you want to ensure that the requested date isn’t too outdated. If nothing is found, you could:

  • ask your customer to come again later (probably not ideal),
  • provisionally charge a VAT anyway and issue a refund once validation is processed and turns out valid (recommended for higher-priced digital products),
  • or you bite the bullet and accept their VAT number for the time being without charging VAT (recommended for lower-priced digital products).

We leave this business decision entirely up to you. Either way you should be transparent and forthcoming to your customers. At the very least, you can ensure whether the VAT number is in a valid format using the valid_format boolean.

4. Webhook Events Are Emitted Proactively

Vatstack will now proactively notify your server as soon as a validation request was successfully processed and a result obtained from VIES. This means that you don’t have to query our API anymore and can instead listen to webhook events.

The payload contains the validation object which you can further process on your end. Configure at which endpoint they should be sent to in your dashboard. You could then reach out to the customer to rectify the situation or adjust your invoice for the next charge.

The following event is generated either immediately (upon succeeded request) or once a validation result was obtained by our scheduler.

validation.succeeded is sent if a response from VIES was obtained.

How You Can Implement the Changes

If you don’t have a Vatstack account, create a new one to get your unique API access key. Fill out the form and confirm your email address by clicking the confirmation button sent to you via email. You can then find your API access key from within the dashboard.

Log into your dashboard, and find the Quick Start section. We’ve refactored the code snippets to get you started within minutes. Simply copy and paste the source code relevant to your programming environment and give it a test run. Or jump directly to our API documentation.

The old endpoint will continue to stay available, but you won’t get to benefit from the changes until you update your application.

More to Come

We’re excited to hear what you think. Send us your feedback to team@vatstack.com. Rest assured that it’s merely our first step to making Vatstack a better partner for your entire stack of VAT obligations and to truly living up to our name.

With this release, we have started with evidence collection for potential audits, record-keeping, downtime handling and automated notifications.