vies-client

Type-safe VIES EU VAT REST API client generated from the official Swagger spec using Orval.

Setup

npm install vies-client

Uses the native fetch API (no extra HTTP dependency).

Usage

Recommended: createViesClient() (no config required)

The client uses the official EU VIES REST API by default.

import { createViesClient } from 'vies-client';

const api = createViesClient();

// Check a VAT number
const result = await api.checkVatNumber({
  countryCode: 'DE',
  vatNumber: '123456789',
});

// Check service status (member state availability)
const status = await api.checkStatus();

To use a different base URL (e.g. for testing): createViesClient('https://your-vies-proxy/rest-api').

Note: Use checkVatNumber for real VAT lookups. The checkVatTestService endpoint on the EC side often returns actionSucceed: false with errorWrappers: [{ error: 'SERVICE_UNAVAILABLE' }]; the API still responds with HTTP 200, so check actionSucceed and errorWrappers when using that endpoint.

Advanced: set base URL only

import { setBaseUrl, getViesOnTheWebEndpoint } from 'vies-client';

// Optional: only if you need a custom base URL
setBaseUrl('https://ec.europa.eu/taxation_customs/vies/rest-api');
const api = getViesOnTheWebEndpoint();
await api.checkVatNumber({ countryCode: 'DE', vatNumber: '123456789' });

Regenerating the client

After changing src/swagger_publicVAT.yaml:

npm run generate
npm run build

Generation is also run automatically on npm publish via prepublishOnly.