# VAT Rates

{% hint style="danger" %}
VatZen is Deprecated since January 2022 and API server will be shut down soon!
{% endhint %}

Keep the rates of your application up-to-date with a regular VAT rate lookup. This ensures that your invoice states the correct VAT across EU Member States. We have also started to add countries outside the EU and will keep them updated.

VAT rates can change irregularly as governments adapt to new circumstances. We track such announcements closely and store scheduled changes in our database. Any such change will take effect at exactly midnight local time of the respective country.

## Rate Entity

Base of the rate endpoint is the `Rate` entity, which is returned from all rates endpoint. You can find the description of the `Rate` entity below:

| Key                            | Type      | Example       | Description                                                                                                              |
| ------------------------------ | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `standard_rate`                | `Number`  | 20            | Standard rate used in the country.                                                                                       |
| `currency`                     | `String`  | `EUR`         | 3-letter ISO 4217 local currency code.                                                                                   |
| `country`                      | `Object`  | N/A           | Contains information about the country                                                                                   |
| `country.code`                 | `String`  | `DE`          | 2-letter ISO country code.                                                                                               |
| `country.name`                 | `String`  | `Germany`     | Corresponding English name of country\_code.                                                                             |
| `country.local_name`           | `String`  | `Deutschland` | Corresponding name of country\_code on local language (in case of multiple national languages, English will be returned) |
| `country.member_state`         | `Boolean` | `false`       | Identifies if the country is a member state or not                                                                       |
| `categories`                   | `Object`  | N/A           | Contains rates for different categories relevant for digital products.                                                   |
| `categories.audiobook`         | `Number`  | `20`          | Rate for audiobooks. Defaults to `standard_rate`                                                                         |
| `categories.broadcasting`      | `Number`  | `10`          | Rate for broadcasting services. Defaults to `standard_rate`                                                              |
| `categories.ebook`             | `Number`  | `10`          | Rate for electronic books. Defaults to `standard_rate`                                                                   |
| `categories.eperiodical`       | `Number`  | `4`           | Rate for electronic periodical. Defaults to `standard_rate`                                                              |
| `categories.eservice`          | `Number`  | `20`          | Rate for electronic services. Defaults to `standard_rate`                                                                |
| `categories.telecommunication` | `Number`  | `30`          | Rate for telecommunication                                                                                               |

## Get All VAT Rates

<mark style="color:blue;">`GET`</mark> `https://api.vatzen.com/v1/rates`

This endpoint allows you fetch all the rates from our system. Before reading this article, familiarize yourself with Authorization and Rate Entity.&#x20;

#### Query Parameters

| Name          | Type    | Description                                                  |
| ------------- | ------- | ------------------------------------------------------------ |
| limit         | integer | Pagination option to limit the page length. Defaults to 100. |
| page          | integer | Page number, defaults to 1.                                  |
| member\_state | boolean | Filter response to include only EU member states.            |

{% tabs %}
{% tab title="200 Rates fetched successfully" %}

```javascript
{
  "success": true,
  "pagination": {
    "has_more": false,
    "total_count": 28
  },
  "rates": [
    {
      "standart_rate": 20,
      "currency": "EUR",
      "country": {
        "code": "AT",
        "name": "Austria",
        "local_name": "Austria",
        "member_state": true
      },
      "categories": {
        "audiobook": 5,
        "broadcasting": 5,
        "ebook": 5,
        "eperiodical": 5,
        "eservice": 20,
        "telecommunication": 20
      }
    }
    // ...
  ]
}
```

{% endtab %}

{% tab title="400 General error. For details, see API Errors page." %}

```javascript
{
  "status": 400,
  "success": false,
  "error": {
    "code": 101,
    "type": "missing_api_key",
    "message": "No API Key provided"
  }
}
```

{% endtab %}
{% endtabs %}

### Response Params

| Key                      | Type          | Value                                                                                          |
| ------------------------ | ------------- | ---------------------------------------------------------------------------------------------- |
| `pagination`             | `Object`      | Information about the pagination                                                               |
| `pagination.has_more`    | `Boolean`     | Identifies if we have more data after this request (e.g. if you need to fetch additional page) |
| `pagination.total_count` | `Number`      | Total items count for your request                                                             |
| `rates`                  | `Array<Rate>` | Array of [Rate Entities.](#rate-entity)                                                        |

## VAT Rate by Country Code

<mark style="color:blue;">`GET`</mark> `https://api.vatzen.com/v1/rate/:country_code`

Returns country's VAT rate by country code provided in path parameter.

#### Path Parameters

| Name          | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| country\_code | string | 2-letter ISO country code. For example "DE". |

{% tabs %}
{% tab title="200 Returns the Rate entity for the country by the county code." %}

```javascript
{
  "success": true,
  "standart_rate": 20,
  "currency": "EUR",
  "country": {
    "code": "AT",
    "name": "Austria",
    "local_name": "Austria",
    "member_state": true
  },
  "categories": {
    "audiobook": 5,
    "broadcasting": 5,
    "ebook": 5,
    "eperiodical": 5,
    "eservice": 20,
    "telecommunication": 20
  }
}
```

{% endtab %}

{% tab title="400 General error, for details see API Errors section" %}

```javascript
{
  "success": false,
  "status": 400,
  "error": {
    "code": 101,
    "type": "missing_api_key",
    "message": "No API Key provided"
  }
}
```

{% endtab %}

{% tab title="404 We were unable to fetch the country by the country code." %}

```javascript
{
  "success": false,
  "status": 404,
  "error": {
    "code": 108,
    "type": "invalid_country_code",
    "message": "You provided invalid count"
  }
}
```

{% endtab %}
{% endtabs %}

## VAT Rate Lookup

<mark style="color:blue;">`GET`</mark> `https://api.vatzen.com/v1/rate`

This method allows you to lookup the VAT rate using different parameters, such as country name, country code, ip address, etc.

#### Query Parameters

| Name            | Type   | Description                                                                                                                         |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| country\_code   | string | 2-digits ISO Country Code. For example "DE"                                                                                         |
| country\_name   | string | English or local country name. For example "Germany"                                                                                |
| ip\_address     | string | IP address of the customer. For example "8.8.8.8". We support both IP v4 and v6 and use extended databases to get the best results. |
| use\_client\_ip | string | We will use IP address coming from the request. This might be helpful is you're making the request from the browser.                |

{% tabs %}
{% tab title="200 Response in case if we've found the correct rate." %}

```javascript
{
  "success": true,
  "standart_rate": 20,
  "currency": "EUR",
  "country": {
    "code": "CH",
    "name": "Switzerland",
    "local_name": "Switzerland",
    "member_state": false
  },
  "categories": {
    "audiobook": 3,
    "broadcasting": 8,
    "ebook": 3,
    "eperiodical": 3,
    "eservice": 8,
    "telecommunication": 8
  }
}
```

{% endtab %}

{% tab title="400 Something went wrong, see API Errors section for error details." %}

```javascript
{
  "success": false,
  "statusCode": 400,
  "error": {
    "code": 107,
    "type": "could_not_resolve_ip",
    "message": "We failed locating the supplied IP Address"
  }
}
```

{% endtab %}

{% tab title="404 We were unable to find the requested country." %}

```javascript
{
  "success": false,
  "statusCode": 404,
  "error": {
    "code": 109,
    "type": "country_not_found",
    "message": "We were unable to find requested country"
  }
}

```

{% endtab %}
{% endtabs %}