VAT Prices Calculations

Using our price endpoints, you may request the API to calculate VAT compliant prices for you.

Hot and Cold Price Calculations

Just as with validations, at VatZen we have a concept of 2 price types: Hot and Cold.

  • Cold prices works in fire-and-forget way. Meaning that you simply call our endpoint and we return you the data, which is never stored afterwards.

  • Hot prices endpoint is different from the cold one in the way that all the requests you make has id's assigned and stored in our DB. And you can always fetch this prices (fetch them all of fetch by id). For example, you can create them on the server side and then retrieve on the client.

Cold validations are performed via price endpoint, end hot validation use prices CRUD endpoints. You can get more details below.

Price Entity

Base of our prices endpoints is the Price entity, which is returned from all pricing-related endpoints. You can find the description of the Pricing entity below:

Field

Type

Example

Description

id

String or null

abc123cba

Uniq id assigned only for hot price calculations. You can use this id to retrieve the price info later.

amount

Object

---

Object, which represents the calculation results.

amount.total_incl_vat

Number

12000

Total amount in cents, including VAT.

amount.total_excl_vat

Number

10000

Total amount in cents, excluding VAT.

amount.vat_amount

Number

2000

VAT amount in cents.

category

String or null

ebook

Category used for calculating the vat rate.

vat_rate

Number

20

VAT Value in percents

country

Object

---

Information about the country, which was the target for your calculations

country.code

String

DE

2 symbol ISO country code

country.name

String

Germany

English name of the country

country.local_name

String

Deutschland

Local name of the country, defaults to English

country.member_state

Boolean

true

Identifies if the requested country a member state or not

get
Calculate Price (Cold Price endpoint)

https://api.vatzen.com/v1/price
This endpoint is accessible with public key. This method is used for price calculations, without storing them in the data base. You just get your result and that's it. If you want to later retrieve you pricing object, please use Hot endpoints (see the description below).
Request
Response
Request
Query Parameters
amount
required
number
Amount in cents to modify by needed rate
vat_included
optional
boolean
If VAT already included in the amount you provide. We will do reverse calculation in this case
category
optional
string
Product category (supported are audiobook, broadcasting, ebook, eperiodical, eservice, telecommunication). If not provided, standard rate would be used
country_code
optional
string
2-digits ISO country code to lookup for the rate
country_name
optional
string
Country name to lookup for the rate
ip_address
optional
string
Customer's IP address to lookup for the VAT rate
use_client_ip
optional
boolean
If we should use IP address from the request to obtain the proper VAT rate
Response
200: OK
Price entity returned with the calculation details
{
"success": true,
"amount": {
"total_excl_vat": 10000,
"total_incl_vat": 10500,
"vat_amount": 500
},
"requested": {
"amount": 10000,
"vat_included": false
},
"category": "audiobook",
"vat_rate": 5,
"country": {
"code": "DE",
"name": "Germany",
"local_name": "Germany",
"member_state": true
}
}

post
Calculate Price and store in the DB

https://api.vatzen.com/v1/prices
Calculates the price, just like the Cold price endpoint, but also stores the price object in our DB, so you can always retrieve it from there.
Request
Response
Request
Query Parameters
amount
required
number
Amount in cents to modify by needed rate
vat_included
optional
boolean
If VAT already included in the amount you provide. We will do reverse calculation in this case
category
optional
string
Product category (supported are audiobook, broadcasting, ebook, eperiodical, eservice, telecommunication). If not provided, standard rate would be used
country_code
optional
string
2-digits ISO country code to lookup for the rate
country_name
optional
string
Country name to lookup for the rate
ip_address
optional
string
Customer's IP address to lookup for the VAT rate
use_client_ip
optional
boolean
If we should use IP address from the request to obtain the proper VAT rate
Response
200: OK
Price entity returned with the calculation details, also id is assigned, which you can use later.
{
"success": true,
"id": "ab123ba",
"amount": {
"total_excl_vat": 10000,
"total_incl_vat": 10500,
"vat_amount": 500
},
"requested": {
"amount": 10000,
"vat_included": false
},
"category": "audiobook",
"vat_rate": 5,
"country": {
"code": "DE",
"name": "Germany",
"local_name": "Germany",
"member_state": true
}
}

get
Get Price by ID

https://api.vatzen.com/v1/prices/:price_id
Returns information about the price by id, which you've got when doing POST request.
Request
Response
Request
Path Parameters
price_id
required
string
Price object id, retrieved from the POST endpoint
Response
200: OK
Price object returned.
{
"success": true,
"id": "ab123ba",
"amount": {
"total_excl_vat": 10000,
"total_incl_vat": 10500,
"vat_amount": 500
},
"requested": {
"amount": 10000,
"vat_included": false
},
"category": "audiobook",
"vat_rate": 5,
"country": {
"code": "DE",
"name": "Germany",
"local_name": "Germany",
"member_state": true
}
}

get
Get All Prices

https://api.vatzen.com/v1/prices
Returns all the prices, paginated
Request
Response
Request
Query Parameters
limit
optional
integer
Limit used for pagination, defaults to 100
page
optional
integer
Page, defaults to 1
Response
200: OK
Returns stored prices
{
"success": true,
"pagination": {
"has_more": true,
"total_count": 10
},
"prices": [
{
"id": "ab123ba",
"amount": {
"total_excl_vat": 10000,
"total_incl_vat": 10500,
"vat_amount": 500
},
"requested": {
"amount": 10000,
"vat_included": false
},
"category": "audiobook",
"vat_rate": 5,
"country": {
"code": "DE",
"name": "Germany",
"local_name": "Germany",
"member_state": true
}
},
// ...
]
}