VAT Sense Python SDK
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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.