Skip to content
EvolveEvolveEvolve

vies

@evolve-framework/vies · v1.0.0

A GraphQL module that checks an EU VAT number live against VIES, the European Commission's VAT information exchange service. ViesVatNumberCheckModule answers vatNumberCheck from the contract in @evolve-framework/schemas: valid or invalid, plus the company name and address when VIES gives them. It needs no API key.

When to use

  • A checkout or registration form validates a business customer's VAT number before it applies VAT-exempt pricing: compose ViesVatNumberCheckModule.
  • A commerce engine checks the number a cart records, such as CartModule's vatNumberCheck in @evolve-framework/commercetools: hand it ViesClient.check, which answers the same three statuses.

It is engine-agnostic, so compose it beside any commerce engine.

Get started

  1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-framework/vies @evolve-framework/core graphql
    Requirements3
    @evolve-framework/core>= 1.8.0 < 2.0.0
    @types/node>=22optional
    graphql>= 16.0.0 < 17.0.0

For example:

import { ViesVatNumberCheckModule } from "@evolve-framework/vies";


export const vatModules = [new ViesVatNumberCheckModule({ retries: 2 })];

Modules

ViesVatNumberCheckModule

Query.vatNumberCheck: whether an EU VAT number is registered, checked live against the European Commission's VIES service, with the company name and address when VIES gives them.

import { ViesVatNumberCheckModule } from "@evolve-framework/vies";
new ViesVatNumberCheckModule(options?: ViesOptions)
OptionTypeDescription
baseUrl?string

Defaults to the European Commission's public VIES REST API.

timeoutMs?number

How long one request may take. Defaults to 8 seconds, as VIES often takes about 5.

retries?number

How often a timed-out request is asked again before the answer is UNKNOWN. Defaults to 1.

fetch?((url: string | URL | Request, options?: RequestInit | undefined, spanName?: string | undefined) => Promise<Response>)

Defaults to the framework's traced fetch.

Extends AbstractModule<unknown>.

Entry points

@evolve-framework/viesViesVatNumberCheckModule, ViesClient and their options3 exports