Checking at checkout

A buyer at checkout should never wait for VIES. VIES relays every query to one of 27 national databases; a member state can be slow or down (Germany is cut every night between 21:40 and 01:00 UTC, see VIES availability), and a single check can take up to 48 seconds before akwito gives up. Nothing makes VIES fast. The recipe is to never put the buyer behind it.

1. Ask with your own patience #

Send the check with max_wait_ms set to what your page can afford — three seconds at checkout, thirty in a back office:

{ "vat_number": "DE811907980", "reference": "order-4821", "max_wait_ms": 3000 }

• 201 Created: VIES answered in time, the check is complete. Apply the reverse charge and move on.
• 202 Accepted: the check is not finished. Keep request_id, accept the order subject to validation, and let the background request finish it. No quota is consumed until it does.

A malformed number never waits: it is refused locally, without any upstream call, as an invalid check with the FORMAT_INVALID or CHECKSUM_INVALID warning. To catch typos before the buyer even submits, call GET /v1/format/{number} as they type: it is free and instant.

2. Be told when it lands #

Register a webhook (see Webhooks): check.completed brings the finished check, check.failed tells you the request could not succeed within 24 hours. Without a webhook, poll poll_url (GET /v1/requests/{id}) with the retry_after it gives.

When the number turns out invalid, invoice with VAT or contact the buyer. This is the rare case: an intra-EU number that fails the format check is caught upfront, and a number that is really unregistered is a minority of checks.

3. Your evidence is dated from the order, not from VIES's mood #

The attempt log of the request records every try, and the attempt certificate (GET /v1/requests/{id}/attestation.pdf) documents the diligence at the date of the order even while VIES is silent. The final check carries the date VIES actually answered. Both together are what an auditor reads.

4. Make known customers instant #

A check served from the 24 hour deduplication window makes no upstream call at all. Put your customer base under Watches: every run leaves a recent check, and a returning customer is answered from it in milliseconds, with a proof dated from the last real consultation.

5. Know before asking #

GET /vies-status.json (no key needed) says which member states are currently unavailable. When the buyer's country is down, tell them upfront that their number will be confirmed by e-mail instead of making them wait.

6. Lookup at checkout, verify later #

verify mode adds a second VIES call to compare the name and address you hold. At checkout, send the number alone (lookup); confirm the identity later, in a watch or a batch, when nobody is waiting.