VAT Validation

Validate VAT identification numbers using the EU VIES system and UK HMRC.

Validate VAT Number

POST /v1/vat/validate

Validates the VAT number format and checks against the official tax authority database.

curl -X POST https://api.shipvat.com/v1/vat/validate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vat_number": "DE123456789"
  }'

Response (Valid)

{
  "valid": true,
  "vat_number": "DE123456789",
  "country_code": "DE",
  "format_valid": true,
  "verification_available": true,
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin",
  "queried_at": "2024-01-15T10:30:00Z"
}

Response (Invalid)

{
  "valid": false,
  "vat_number": "DE000000000",
  "country_code": "DE",
  "format_valid": true,
  "verification_available": true,
  "error": "VAT number not found in VIES database",
  "queried_at": "2024-01-15T10:30:00Z"
}

Response (Service Unavailable)

{
  "valid": false,
  "vat_number": "DE123456789",
  "country_code": "DE",
  "format_valid": true,
  "verification_available": false,
  "message": "VIES service temporarily unavailable, format is valid",
  "queried_at": "2024-01-15T10:30:00Z"
}

Check Format Only

GET /v1/vat/format-check

Validates the VAT number format without querying the tax authority (faster, no rate limits). Useful for client-side validation before submitting.

Query Parameters

Parameter	Type	Required	Description
`vat_number`	string	Yes	The VAT number to check

curl "https://api.shipvat.com/v1/vat/format-check?vat_number=DE123456789" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "vat_number": "DE123456789",
  "country_code": "DE",
  "format_valid": true,
  "expected_format": "DE + 9 digits",
  "queried_at": "2024-01-15T10:30:00Z"
}

List VAT Countries

GET /v1/vat/countries

Returns all countries with VAT validation support.

curl https://api.shipvat.com/v1/vat/countries \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "countries": [
    {
      "code": "AT",
      "name": "Austria",
      "format": "ATU + 8 digits",
      "example": "ATU12345678",
      "verification_service": "VIES"
    },
    {
      "code": "DE",
      "name": "Germany",
      "format": "DE + 9 digits",
      "example": "DE123456789",
      "verification_service": "VIES"
    },
    {
      "code": "GB",
      "name": "United Kingdom",
      "format": "GB + 9 or 12 digits",
      "example": "GB123456789",
      "verification_service": "HMRC"
    }
  ],
  "total": 30
}

VAT Number Formats

Country	Code	Format	Example
Austria	AT	ATU + 8 digits	ATU12345678
Belgium	BE	BE + 10 digits	BE0123456789
Germany	DE	DE + 9 digits	DE123456789
France	FR	FR + 2 chars + 9 digits	FR12345678901
Italy	IT	IT + 11 digits	IT12345678901
Netherlands	NL	NL + 9 digits + B + 2 digits	NL123456789B01
Spain	ES	ES + letter + 7 digits + letter	ESA12345678
UK	GB	GB + 9 or 12 digits	GB123456789

Validate and Update Customer

Validate a VAT number and update a customer record in one call. This is a convenience endpoint that validates the VAT and saves the result to the customer.

POST /v1/vat/validate-customer/:customerId

curl -X POST https://api.shipvat.com/v1/vat/validate-customer/cust_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vat_number": "DE123456789"
  }'

Response

{
  "customer_id": "cust_abc123",
  "valid": true,
  "vat_number": "DE123456789",
  "country_code": "DE",
  "format_valid": true,
  "verification_available": true,
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin",
  "customer_updated": true,
  "queried_at": "2024-01-15T10:30:00Z"
}

B2B Reverse Charge

When both seller and buyer have valid EU VAT numbers in different countries, the reverse charge mechanism applies (0% VAT).

# 1. Validate customer's VAT
curl -X POST https://api.shipvat.com/v1/vat/validate \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"vat_number": "DE123456789"}'

# 2. Calculate tax (will return 0% if reverse charge applies)
curl -X POST https://api.shipvat.com/v1/calculate \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "line_items": [{"amount": 10000, "product_type": "saas", "quantity": 1}],
    "customer": {
      "address": {"country": "DE"},
      "vat_id": "DE123456789",
      "vat_id_valid": true
    },
    "seller": {"registered_in": ["FR"], "vat_id": "FR12345678901"},
    "currency": "EUR"
  }'