# VAT Prices Calculations {% hint style="danger" %} VatZen is Deprecated since January 2022 and API server will be shut down soon! {% endhint %} ### 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 | {% tabs %} {% tab title="200 Price entity returned with the calculation details" %} ```javascript { "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 } } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 Price entity returned with the calculation details, also id is assigned, which you can use later." %} ```javascript { "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 } } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 Price object returned." %} ```javascript { "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 } } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 Returns stored prices" %} ```javascript { "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 } }, // ... ] } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.vatzen.com/api/calculate-price.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.