Skip to main content

VAT Sense Python SDK

PyPI version

The official Python library for the VAT Sense REST API. Validate VAT/EORI numbers, look up VAT/GST rates, calculate prices, convert currencies, and generate VAT-compliant invoices.

Includes type definitions for all request params and response fields, and offers both synchronous and asynchronous clients powered by httpx.

Installation

pip install vatsense

Requires Python 3.9+.

Quick start

Create a client using your API key from the VAT Sense dashboard. The API uses HTTP Basic Auth with user as the username and your API key as the password.

from vat_sense import VatSense

client = VatSense(
    username="user",
    password="your_api_key",
)

You can also set the VAT_SENSE_USERNAME and VAT_SENSE_PASSWORD environment variables and the client will pick them up automatically.

Validate a VAT number

response = client.validate.check(vat_number="GB288305674")

if response.data.valid:
    print(response.data.company.company_name)     # "BRITISH BROADCASTING CORPORATION"
    print(response.data.company.company_address)
    print(response.data.company.country_code)      # "GB"

VAT validation works for the UK, EU, Australia, Norway, Switzerland, South Africa, and Brazil.

Validate an EORI number

response = client.validate.check(eori_number="GB123456789000")

if response.data.valid:
    print(response.data.company.company_name)

EORI validation is available for UK and EU numbers only.

Get a consultation number

If you need an official consultation number from VIES (EU) or HMRC (UK), provide your own VAT number as the requester:

response = client.validate.check(
    vat_number="FR12345678901",
    requester_vat_number="FR98765432101",
)

print(response.data.consultation_number)

Note: GB requester numbers only work for GB validations, and EU requester numbers only work for EU validations. Cross-region requests are not supported.

If you would rather have an answer than wait for a consultation number when VIES is down, send consultation_optional=True. Where a national register can confirm the number, you get the answer with no consultation_number instead of the 412:

response = client.validate.check(
    vat_number="FR12345678901",
    requester_vat_number="FR98765432101",
    consultation_optional=True,
)

Check many numbers at once (batches)

A batch checks a list of VAT numbers, as the dashboard's bulk validator does with a file. Batch calls are free and each number checked counts as one request. With a test key the batch is answered from the test numbers and costs nothing.

import time

batch = client.batches.create(
    numbers=["GB288305674", "FR12345678901"],
    reference="November customers",
    idempotency_key="november-customers",
).data

while client.batches.retrieve(batch.id).data.status not in ("complete", "paused", "expired"):
    time.sleep(10)

after = 0
while True:
    page = client.batches.results(batch.id, after=after, limit=1000).data
    for row in page.data:
        print(row.vat_number, row.result, row.company_name)
    if not page.has_more:
        break
    after = page.next_after

csv_report = client.batches.results_csv(batch.id)

Use rows=[{"vat_number": ..., "company_name": ..., "postcode": ...}] instead of numbers for company matching. A batch can also be paused, continued (continue_), completed and, while a draft, deleted. Instead of polling, take the batch.completed webhook.

Check a webhook's signature

Every webhook event carries a VatSense-Signature header. Check it against the raw request body with the endpoint's signing secret before trusting the event:

from vat_sense.webhooks import construct_event, WebhookSignatureError

try:
    event = construct_event(raw_body, headers["VatSense-Signature"], "whsec_...")
except WebhookSignatureError:
    return 400  # not from VAT Sense, or too old

if event["type"] == "batch.completed":
    ...

Events more than 5 minutes old are refused (change it with tolerance=). During the 24 hours after a secret is rolled, events signed with either secret are accepted.

Find the VAT rate for a country

rate = client.rates.find(country_code="DE")

print(rate.data.country_name)       # "Germany"
print(rate.data.tax_rate.rate)      # 19.0
print(rate.data.tax_rate.class_)    # "standard"

Find a rate for a specific product type

rate = client.rates.find(country_code="DE", type="ebooks")

print(rate.data.tax_rate.rate)      # 7.0
print(rate.data.tax_rate.class_)    # "reduced"

Find a rate by IP address

Useful for determining the correct rate based on your customer's location:

rate = client.rates.find(ip_address="185.86.151.11")

print(rate.data.country_code)       # "GB"
print(rate.data.tax_rate.rate)      # 20.0

Calculate a VAT-inclusive price

result = client.rates.calculate_price(
    price="100.00",
    tax_type="excl",
    country_code="FR",
)

print(result.data.vat_price.price_incl_vat)  # Price including VAT
print(result.data.vat_price.price_excl_vat)  # Price excluding VAT
print(result.data.vat_price.vat_rate)        # VAT rate applied
print(result.data.vat_price.vat)             # VAT amount

List all VAT rates

rates = client.rates.list()

for rate in rates.data:
    print(f"{rate.country_code}: {rate.country_name}")

# Filter to EU countries only
eu_rates = client.rates.list(eu=True)

Async usage

An async client is also available:

import asyncio
from vat_sense import AsyncVatSense

client = AsyncVatSense(
    username="user",
    password="your_api_key",
)

async def main():
    response = await client.validate.check(vat_number="GB288305674")
    print(response.data.valid)

asyncio.run(main())

Handling errors

When the API returns an error, the library raises a typed exception:

from vat_sense import VatSense, APIConnectionError, APIStatusError, RateLimitError

client = VatSense(username="user", password="your_api_key")

try:
    response = client.validate.check(vat_number="GB288305674")
except APIConnectionError:
    # Network issue, could not reach the API
    print("Connection failed")
except RateLimitError:
    # 429: Too many requests (300/min general limit, 3/sec for UK validation)
    print("Rate limited, try again shortly")
except APIStatusError as e:
    # Covers all other HTTP errors
    print(e.status_code)
    print(e.message)

A 412 error means the upstream validation service (VIES, HMRC, etc.) is temporarily unavailable. These requests do not count against your usage quota.

Status Code Error Type
400 BadRequestError
401 AuthenticationError
404 NotFoundError
409 ConflictError
429 RateLimitError
>= 500 InternalServerError
N/A APIConnectionError

Retries

Failed requests are automatically retried up to 2 times with exponential backoff. This includes connection errors, timeouts, 429, and 5xx responses.

# Disable retries
client = VatSense(username="user", password="your_api_key", max_retries=0)

# Or configure per request
response = client.validate.check(vat_number="GB288305674", timeout=5.0)

Available services

Service Description
client.validate Validate VAT and EORI numbers
client.rates VAT/GST rate lookups, price calculations
client.countries Country data and province lookups
client.currency Exchange rates and currency conversion
client.batches Check many VAT numbers in one batch
client.invoice Create and manage VAT-compliant invoices
client.usage Check your API usage

Documentation

Full API documentation is available at vatsense.com/documentation.

Versioning

This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs may change at any time.

Contributing

See the contributing documentation.

Metadata

Release files for vatsense 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vatsense 0.8.0
File Size Uploaded Provenance Actions
vatsense-0.8.0.tar.gz 257.6 kB Without provenance Details for vatsense-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vatsense 0.8.0
File Interpreter ABI Platform Actions
vatsense-0.8.0-py3-none-any.whl Python 3 none any Details for vatsense-0.8.0-py3-none-any.whl

Total release size: 388.9 kB

Release files / vatsense-0.8.0.tar.gz

Download URL vatsense-0.8.0.tar.gz
Size 257.6 kB
Tags Source
SHA-256 checksum
How to use checksums
224a607c74e3a9ba8018b3053b618539f92d4db8a4a980a2a7ed669e20fbb7d8
BLAKE2b-256 checksum
How to use checksums
52b26d5d1dcdc88df7460180dcc94007f2a8f2cf69e73374f3769af6262cc06c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / vatsense-0.8.0-py3-none-any.whl

Download URL vatsense-0.8.0-py3-none-any.whl
Size 131.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a255b41bf8fd6a86264cf001bb5a657a429b1d9974e21d81493a88bbf336bb92
BLAKE2b-256 checksum
How to use checksums
e1e124cffb449e6ce52b71e57571e44b1279a038a040b4a04fd0e0d5609b49e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for vatsense 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page