VAT Prices Calculations

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

VatZen is Deprecated since January 2022 and API server will be shut down soon!

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

Calculate Price (Cold Price endpoint)

GET 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).

Query Parameters

Name	Type	Description
amount	number	Amount in cents to modify by needed rate
vat_included	boolean	If VAT already included in the amount you provide. We will do reverse calculation in this case
category	string	Product category (supported are audiobook, broadcasting, ebook, eperiodical, eservice, telecommunication). If not provided, standard rate would be used
country_code	string	2-digits ISO country code to lookup for the rate
country_name	string	Country name to lookup for the rate
ip_address	string	Customer's IP address to lookup for the VAT rate
use_client_ip	boolean	If we should use IP address from the request to obtain the proper VAT rate

200 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
  }
}

Calculate Price and store in the DB

POST 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.

Query Parameters

Name	Type	Description
amount	number	Amount in cents to modify by needed rate
vat_included	boolean	If VAT already included in the amount you provide. We will do reverse calculation in this case
category	string	Product category (supported are audiobook, broadcasting, ebook, eperiodical, eservice, telecommunication). If not provided, standard rate would be used
country_code	string	2-digits ISO country code to lookup for the rate
country_name	string	Country name to lookup for the rate
ip_address	string	Customer's IP address to lookup for the VAT rate
use_client_ip	boolean	If we should use IP address from the request to obtain the proper VAT rate

200 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 Price by ID

GET https://api.vatzen.com/v1/prices/:price_id

Returns information about the price by id, which you've got when doing POST request.

Path Parameters

Name	Type	Description
price_id	string	Price object id, retrieved from the POST endpoint

200 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 All Prices

GET https://api.vatzen.com/v1/prices

Returns all the prices, paginated

Query Parameters

Name	Type	Description
limit	integer	Limit used for pagination, defaults to 100
page	integer	Page, defaults to 1

200 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
      }
    },
    // ...
  ]
}