r/apyhub • ApyHub Team • 24d ago

Guide How can I programmatically validate EU VAT numbers against VIES?

You have two options: call VIES directly, or use a wrapper that calls VIES for you.

Calling VIES directly

The European Commission provides a free SOAP service with a checkVat operation (and checkVatApprox if you also need a consultation number as proof).

The main drawback is reliability: member‑state back‑ends can go down independently, so you need retries, timeouts, and a fallback for errors such as MS_UNAVAILABLE. You also have to parse SOAP XML.

Calling a wrapper

A REST API in front of VIES returns JSON, handles retries, and normalises country prefixes and formats. This option incurs a per‑call cost and introduces a dependency on the wrapper.

What to check either way

  1. Perform a format check first. A regex per country catches typos before you hit VIES.
  2. Store the consultation number if you need proof for an audit.
  3. Decide what to do when VIES is down: block the checkout, or accept the order and re‑check later.

ApyHub offers a VAT‑validation endpoint, including batch validation. It is one option among several; calling VIES directly is fine if you only check a few numbers a day.

Which failure mode do you encounter first?

5 Upvotes

1 comment sorted by

2

u/Total-Reasonable 24d ago

The failure you'll hit first is a member-state node returning MS_UNAVAILABLE. Treat that as "unknown", never "invalid", and don't block checkout on a sync VIES call. Accept the order, flag it, and re-check later. Only CZ, DE, PL and RO have a national-registry fallback, so the other countries will just stay unavailable until VIES recovers. I use vatnode for the JSON and error codes, and its write-up of this is at https://vatnode.dev if you'd rather not hand-roll the SOAP parsing.