# VAT & Sales Tax API
> VAT, GST and sales-tax rates for 128 countries — plus US state and Canadian province sub-rates — with a built-in tax calculator. Get the standard rate for any country (e.g. DE → 19%), compute the tax and gross total on a net amount (e.g. €100 in Germany → €19 tax, €119 total), apply a US state or Canadian province rate, or list every country. Ideal for e-commerce checkouts, invoicing, SaaS billing and pricing tools. (Standard rates, not tax advice.)

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/vat-api/..."
```

## Pricing
- **Free** (Free) — 2,500 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 45,000 calls/Mo, 8 req/s
- **Pro** ($22/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($58/Mo) — 1,100,000 calls/Mo, 50 req/s

## Endpoints

### Tax

#### `GET /v1/calculate` — Calculate tax & gross total on a net amount

**Parameters:**
- `country` (query, required, string) — 2-letter ISO country code Example: `DE`
- `amount` (query, required, string) — Net amount Example: `100`
- `state` (query, optional, string) — US state / Canadian province code (e.g. CA)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vat-api/v1/calculate?country=DE&amount=100"
```

**Response:**
```json
{
    "data": {
        "net": 100,
        "tax": 19,
        "rate": 0.19,
        "type": "vat",
        "gross": 119,
        "scope": "DE",
        "state": null,
        "country": "DE",
        "currency": "EUR",
        "rate_percent": 19
    },
    "meta": {
        "timestamp": "2026-05-31T03:08:48.139Z",
        "request_id": "b953bcdb-070f-4c72-9ddf-436498ba2882"
    },
    "status": "ok",
    "message": "Tax calculated",
    "success": true
}
```

#### `GET /v1/country` — VAT / tax rate for a country

**Parameters:**
- `code` (query, required, string) — 2-letter ISO country code Example: `DE`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vat-api/v1/country?code=DE"
```

**Response:**
```json
{
    "data": {
        "rate": 0.19,
        "type": "vat",
        "country": "DE",
        "currency": "EUR",
        "country_name": "Germany",
        "rate_percent": 19
    },
    "meta": {
        "timestamp": "2026-05-31T03:08:48.213Z",
        "request_id": "bc265055-0201-40f5-b6a6-7a6cff645a9e"
    },
    "status": "ok",
    "message": "Country tax retrieved",
    "success": true
}
```

#### `GET /v1/list` — All countries with their headline rate

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vat-api/v1/list"
```

**Response:**
```json
{
    "data": {
        "count": 128,
        "countries": [
            {
                "type": "vat",
                "country": "AD",
                "currency": "EUR",
                "country_name": "Andorra",
                "rate_percent": 4.5
            },
            {
                "type": "vat",
                "country": "AE",
                "currency": "AED",
                "country_name": "United Arab Emirates",
                "rate_percent": 5
            },
            {
                "type": "gst",
                "country": "AI",
                "currency": "XCD",
                "country_name": "Anguilla",
                "rate_percent": 13
            },
            {
                "type": "vat",
                "country": "AL",
                "currency": "ALL",
                "country_name": "Albania",
                "rate_percent": 20
            },
            {
                "type": "vat",
                "country": "AM",
                "currency": "AMD",
                "country_name": "Armenia",
                "rate_percent": 20
            },
            {
                "type": "vat",
                "country": "AO",
                "currency": "AOA",
                "country_name": "Angola",
                "rate_percent": 14
            },
            {
                "type": "vat",
                "country": "AR",
                "currency": "ARS",
                "country_name": "Argentina",
                "rate_percent": 
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & source

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vat-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Headline standard rates; sub-rates for US states and Canadian provinces. Not tax advice.",
        "total": 128,
        "types": [
            "vat",
            "gst",
            "none"
        ],
        "source": "node-sales-tax dataset",
        "with_state_rates": 3
    },
    "meta": {
        "timestamp": "2026-05-31T03:08:48.328Z",
        "request_id": "fee73ab8-ff98-4c67-8058-5dc89a5a2769"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/vat-api
OpenAPI spec: https://www.oanor.com/api/vat-api/openapi.json