CheKin Taxes API

Quick Links:

Getting Started:

Account: First you need to get an account. Contact our sales team at partners@chekin.io and they will create an account for you with an email and password.

Token: Use your email & password to get a token using our API:

					
POST https://a.chekin.io/api/v3/token/
{
	"email": "your@user",
	"password": "yourpassword"
}
Response:
{
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiN2JkMzU4NzEyYzJiNDY3ODllM2Y3ZjY1Y2UyM2FlYjgiLCJ1c2VybmFtZSI6Im1hcmlhbm9AY2hla2luLmlvIiwiZXhwIjoxNTcxMjU2OTA2LCJvcmlnX2lhdCI6MTU3MTI1MzMwNiwiaXNfb2NyX2VuYWJsZSI6ZmFsc2UsImZhY2VfZXh0IjpmYWxzZSwib2NyX3ZpeiI6ZmFsc2UsIm9jcl9iYXJjb2RlcyI6ZmFsc2V9.yEYTAeTs3omjqyX4nkWyIogmWcANn-XkUTz2k220Hlg"
}

The token expires within 1 hour, but the same endpoint can be called to get a new one.

Headers: Add these headers in all your following requests:
- Content-Type application/json
- Authorization JWT {{your token}}

Steps for calculating taxes:

In this section we will see how to calculate taxes for each country.

The steps are the following.

Get location: We obtain the locations of a specific country. We specify that in the country parameter by assigning the ISO2 code of each country.

Copy Code

					
GET https://a.chekin.io/api/v3/tax/locations/?country=IT
Response:
[
    {
        "id": "aee0d11af69c4ad68d717407ea0779ad",
        "country": "IT",
        "region": "Abruzzo",
        "province": "''",
        "province_id": "''",
        "city": "Pescasseroli",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    },
    ...
]

Note: enable_total_price is enabled to true when location don´t have price per night

Get property type: We obtain the locations of a specific country. We specify that in the country parameter by assigning the ISO2 code of each country.

Copy Code

					GET https://a.chekin.io/api/v3/tax/property-types/?country=IT
Response:
[
    {
        "id": "e2909ee4-24f9-4aae-a4f4-4b31fa4fced0",
        "label": "CAMPING",
        "region_id": null,
        "country_id": "IT",
        "housing_type": "CAM"
    },
    ...
]

Get property subtype (Only some countries have it): We obtain the locations of a specific country. We specify that in the country parameter by assigning the ISO2 code of each country.

Copy Code

					GET https://a.chekin.io/api/v3/tax/property-subtypes/?country=IT
Response:
[
    {
        "id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
        "label": "1 star",
        "country_id": "IT",
        "housing_subtype": "STA1"
    },
    ...
]

Get Regions (Only Spain): We obtain the regions of Spain.

Copy Code

					
GET http://api-ng.chekintest.xyz/api/v3/tax/regions/
Response:
[
    {
        "id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
        "name": "Catalonia",
        "country_id": "ES"
    },
    ...
]

Tax calculation: The local taxes are calculated depending on the type of housing
The necessary parameters are as follows:

country_id: country code ISO2
property_type_id: ID of property type
property_subtype_id: ID of property subtype (needed only on Italy and some city con Republic Czech)
location_id: ID of location
birth_dates (list of birth dates of guests) or ages (calculated ages of guests). Only one of both can be sent and not both at the same time.
nights_number: number of nights of reservationTax calculation: The local taxes are calculated depending on the type of housing.
date: date of reservation

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "IT",
	"property_type_id": "e2909ee4-24f9-4aae-a4f4-4b31fa4fced0",
     	"property_subtype_id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
	"location_id": "aee0d11af69c4ad68d717407ea0779ad",
	"ages": [28, 20],
	"nights_number": 3,
	"date": "2019-10-31"
}

The response add extra fields:

tax: the final value of the tax to be paid
currency: the currency of the country
vat: specified percentage of tax (by now, only for Germany)
iva: This term is the same as vat only shown in Spanish properties
total_fee: total tax to pay (by now, only for Germany, Spain)

Copy Code

					Response:
{
    "property_type_id": "e2909ee4-24f9-4aae-a4f4-4b31fa4fced0",
    "property_subtype_id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
    "date": "2019-10-31",
    "country_id": "IT",
    "location_id": "aee0d11a-f69c-4ad6-8d71-7407ea0779ad",
    "nights_number": 3,
    "tax": 12.0,
    "currency": "EUR",
    "ages": [
        28,
        20
    ]
}

Use Case ITALY: Calculate taxes for city Pescasseroli on property type CAMPING and property subtype 1 Star

Copy Code

					
  Location:
    {
        "id": "aee0d11af69c4ad68d717407ea0779ad",
        "country": "IT",
        "region": "Abruzzo",
        "province": "''",
        "province_id": "''",
        "city": "Pescasseroli",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
 
    Property Type:
    {
        "id": "e2909ee4-24f9-4aae-a4f4-4b31fa4fced0",
        "label": "CAMPING",
        "region_id": null,
        "country_id": "IT",
        "housing_type": "CAM"
    }
 
 
Property subtype:
{
          "id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
          "label": "1 star",
          "country_id": "IT",
          "housing_subtype": "STA1"
       }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "IT",
	"property_type_id": "e2909ee4-24f9-4aae-a4f4-4b31fa4fced0",
     	"property_subtype_id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
	"location_id": "aee0d11af69c4ad68d717407ea0779ad",
	"ages": [28, 20],
	"nights_number": 3,
	"date": "2019-10-31"
}
Response:
{
    "property_type_id": "e2909ee4-24f9-4aae-a4f4-4b31fa4fced0",
    "property_subtype_id": "0e93e515-7dd8-4d85-8d5b-e77d7ad25a9d",
    "date": "2019-10-31",
    "country_id": "IT",
    "location_id": "aee0d11a-f69c-4ad6-8d71-7407ea0779ad",
    "nights_number": 3,
    "tax": 12.0,
    "currency": "EUR",
    "ages": [
        28,
        20
    ]
}

Use Case AUSTRIA: Calculate taxes for city Eisenstadt on property type Campsites

Copy Code

					
Location:
    {
        "id": "740defe00f374077938dda9f97cd8f51",
        "country": "AT",
        "region": "Burgenland",
        "province": "''",
        "province_id": "''",
        "city": "Eisenstadt",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
 
 
    Property Type:
    {
        "id": "fca52bc3-6621-4930-b2b2-27eee0e3a259",
        "label": "Campsites",
        "region_id": null,
        "country_id": "AT",
        "housing_type": "CST"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "AT",
	"property_type_id": "fca52bc3-6621-4930-b2b2-27eee0e3a259",
	"location_id": "740defe0-0f37-4077-938d-da9f97cd8f51",
	"ages": [28, 20],
	"nights_number": 3,
	"date": "2019-10-31"
}
Response:
{
    "property_type_id": "fca52bc3-6621-4930-b2b2-27eee0e3a259",
    "date": "2018-01-01",
    "country_id": "AT",
    "location_id": "740defe0-0f37-4077-938d-da9f97cd8f51",
    "nights_number": 2,
    "tax": 9.0,
    "currency": "EUR",
    "ages": [
        255,
        255,
        255
    ]
}

Use Case BELGIUM: Calculate taxes for city Luxembourg on property type Hostels

Copy Code

					
 Location:
    {
        "id": "2ddea382abdf4c81890a1e0b9d833cdb",
        "country": "BE",
        "region": "Luxembourg",
        "province": "''",
        "province_id": "''",
        "city": "Virton",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
       Property Type:
    {
        "id": "bddc5028-28ae-4da6-86a1-6a5c16949544",
        "label": "Hostels",
        "region_id": null,
        "country_id": "BE",
        "housing_type": "MOT"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "BE",
	"property_type_id": "bddc5028-28ae-4da6-86a1-6a5c16949544",
	"location_id": "2ddea382-abdf-4c81-890a-1e0b9d833cdb",
	"date": "2019-10-31",
	"ages": [11,22],
	"nights_number": 2,
}
Response:
{
    "property_type_id": "bddc5028-28ae-4da6-86a1-6a5c16949544",
    "country_id": "BE",
    "location_id": "2ddea382-abdf-4c81-890a-1e0b9d833cdb",
    "nights_number": 2,
    "date": "2019-10-31",
    "tax": 4.0,
    "currency": "EUR",
    "ages": [
        11,
        22
    ]
}

Use Case CZECH REPUBLIC: Calculate taxes for city Pisek on property type General Accomodation

Copy Code

					
 Location:
    {
        "id": "7126fc823c0d4089bf424b528ebc7732",
        "country": "CZ",
        "region": "Bohemia Meridional (Jihočeský kraj)",
        "province": "",
        "province_id": "",
        "city": "Písek",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
       Property Type:
    {
        "id": "cde76767-2f2d-48af-9dce-6ec5d05b0c5e",
        "label": "GENERAL ACCOMMODATION",
        "region_id": null,
        "country_id": "CZ",
        "housing_type": "OTH"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "CZ",
	"property_type_id": "cde76767-2f2d-48af-9dce-6ec5d05b0c5e",
	"location_id": "7126fc82-3c0d-4089-bf42-4b528ebc7732",
	"ages": [40,37,17],
	"date": "2019-10-31",
	"nights_number": 2,
}
Response:
{
    "property_type_id": "cde76767-2f2d-48af-9dce-6ec5d05b0c5e",
    "country_id": "CZ",
    "location_id": "7126fc82-3c0d-4089-bf42-4b528ebc7732",
    "nights_number": 1,
    "date": "2019-10-31",
    "tax": 12.0,
    "currency": "CZK",
    "ages": [
        40,
        37,
        17
    ]
}

Use Case FRANCE: Calculate taxes for city Paris on property type Palaces

Copy Code

					
  Location:
    {
        "id": "2a92aa001b624658a118c845223c44b8",
        "country": "FR",
        "region": "Paris",
        "province": "''",
        "province_id": "''",
        "city": "PARIS",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
       Property Type:
    {
        "id": "97a289c8-dba9-422b-822f-619bfbad31dc",
        "label": "Palaces",
        "region_id": null,
        "country_id": "FR",
        "housing_type": "PAL"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "FR",
	"property_type_id": "97a289c8-dba9-422b-822f-619bfbad31dc",
	"location_id": "2a92aa001b624658a118c845223c44b8",
	"ages": [18,4,22],
	"date": "2019-10-31",
	"nights_number": 2,
	"cost_per_night": "3.00"
}
Response:
{
    "property_type_id": "97a289c8-dba9-422b-822f-619bfbad31dc",
    "country_id": "FR",
    "location_id": "2a92aa00-1b62-4658-a118-c845223c44b8",
    "nights_number": 2,
    "date": "2019-10-31",
    "tax": 20.0,
    "currency": "EUR",
    "ages": [
        18,
        4,
        22
    ],
    "cost_per_night": "3.00"
}

Use Case GERMANY (City need total price): Calculate taxes for city Berlin on property type General

Copy Code

					
 Location:
    {
        "id": "99c62e122a8348538997d6ac7039bb12",
        "country": "DE",
        "region": "Berlin",
        "province": "",
        "province_id": "",
        "city": "Berlin",
        "area": "AR1",
        "subarea": "",
        "district": "",
        "enable_total_price": true,
        "location_name": "Berlin--Berlin-Area I-"
    }
       Property Type:
    {
        "id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
        "label": "GENERAL GERMANY",
        "region_id": null,
        "country_id": "DE",
        "housing_type": "OTH"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "DE",
	"property_type_id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
	"location_id": "99c62e122a8348538997d6ac7039bb12",
	"ages": [19,10,35],
	"date": "2019-10-31",
	"nights_number": 2,
	"reservation_total_price": "45.00"
}
Response:
{
    "property_type_id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
    "country_id": "DE",
    "location_id": "99c62e12-2a83-4853-8997-d6ac7039bb12",
    "nights_number": 30,
    "date": "2019-10-31",
    "tax": 1.58,
    "vat": 0.11,
    "total_fee": 2.69,
    "currency": "EUR",
    "ages": [
        19,
        10,
        35
    ],
    "reservation_total_price": "45.00"
}

Use Case GERMANY: Calculate taxes for city Bad Belzig on property type General

Copy Code

					
Location:
    {
        "id": "e6cb725effcd4839bdb174d1b3b03721",
        "country": "DE",
        "region": "Bradenburg",
        "province": "",
        "province_id": "",
        "city": "Bad Belzig",
        "area": "AR1",
        "subarea": "",
        "district": "",
        "enable_total_price": false,
        "location_name": "Bradenburg--Bad Belzig-Area I-"
    }
       Property Type:
    {
        "id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
        "label": "GENERAL GERMANY",
        "region_id": null,
        "country_id": "DE",
        "housing_type": "OTH"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "DE",
	"property_type_id": "c6e12ea3-7d6a-4222-8418-b7a8f95ec19a",
	"location_id": "e6cb725effcd4839bdb174d1b3b03721",
	"ages": [24,19],
	"nights_number": 2,
	"date": "2019-10-31"
}
Response:
{
    "property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
    "date": "2019-10-31",
    "country_id": "DE",
    "location_id": "e6cb725e-ffcd-4839-bdb1-74d1b3b03721",
    "nights_number": 2,
    "tax": 6.0,
    "vat": 0.42,
    "total_fee": 6.42,
    "currency": "EUR",
    "ages": [
        24,
        19
    ]
}

Use Case HUNGARY (City need total price): Calculate taxes for city Budavar on property type General

Copy Code

					
 Location:
    {
        "id": "7577dc1d46054ae0a9f1e53090a88aab",
        "country": "HU",
        "region": "Central Hungary",
        "province": "Budapest",
        "province_id": "''",
        "city": "District I (budavar)",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": true
    }
       Property Type:
    {
        "id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
        "label": "GENERAL",
        "region_id": null,
        "country_id": "HU",
        "housing_type": "OTH"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "HU",
	"property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
	"location_id": "7577dc1d46054ae0a9f1e53090a88aab",
	"date": "2019-10-31",
	"nights_number": 1,
	"reservation_total_price": 50000
}
Response:
{
    "property_type_id": "a4aafe73-2a51-44c9-ad64-a8ad78d9bbe5",
    "country_id": "HU",
    "location_id": "7577dc1d-4605-4ae0-a9f1-e53090a88aab",
    "nights_number": 1,
    "tax": 2000.0,
    "currency": "HUF",
    "ages": [],
    "reservation_total_price": "50000.00"
}

Use Case HUNGARY: Calculate taxes for city Zalalovo on property type General

Copy Code

					
 Location:
    {
        "id": "7802245bb9284fe6a0922ff823e8aec2",
        "country": "HU",
        "region": "Western Transdanubia",
        "province": "Zala",
        "province_id": "''",
        "city": "Zalalövő",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
       Property Type:
    {
        "id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
        "label": "GENERAL",
        "region_id": null,
        "country_id": "HU",
        "housing_type": "OTH"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "HU",
	"property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
	"location_id": "7802245bb9284fe6a0922ff823e8aec2",
	"date": "2019-10-31",
	"nights_number": 1,
}
Response:
{
    "property_type_id": "41d5af67-dc8f-419d-92ed-ac60b4552bb8",
    "country_id": "HU",
    "location_id": "7802245b-b928-4fe6-a092-2ff823e8aec2",
    "nights_number": 2,
    "tax": 1400.0,
    "currency": "HUF",
    "ages": [
        11,
        22,
        21
    ]
}

Use Case NETHERLANDS: Calculate taxes for city Middelburg on property type Bed and Breakfast

Copy Code

					
 Location:
    {
        "id": "35c4105c3d034b0f97bbd795b894a17d",
        "country": "NL",
        "region": "Dutch Flanders",
        "province": "''",
        "province_id": "''",
        "city": "Middelburg",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
       Property Type:
    {
        "id": "48be6c38-17df-4f54-b35e-374aab28e7fc",
        "label": "Bed and breakfast",
        "region_id": null,
        "country_id": "NL",
        "housing_type": "BBF"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "NL",
	"property_type_id": "48be6c38-17df-4f54-b35e-374aab28e7fc",
	"location_id": "35c4105c3d034b0f97bbd795b894a17d",
	"date": "2019-01-01",
	"ages": [13, 13, 20]
	"nights_number": 2,
	"cost_per_night": "3.00"
}

Response:
{
    "property_type_id": "48be6c38-17df-4f54-b35e-374aab28e7fc",
    "date": "2019-01-01",
    "country_id": "NL",
    "location_id": "35c4105c-3d03-4b0f-97bb-d795b894a17d",
    "nights_number": 2,
    "tax": 12.0,
    "currency": "EUR",
    "ages": [
        13,
        13,
        20
    ],
    "cost_per_night": "3.00"
}

Use Case PORTUGAL: Calculate taxes for city Porto on property type General

Copy Code

					
  Location:
    {
        "id": "422149c2b47a4656822a4de5765bde15",
        "country": "PT",
        "region": "''",
        "province": "''",
        "province_id": "''",
        "city": "Porto",
        "area": "",
        "subarea": "",
        "district": "",
        "enable_total_price": false
    }
       Property Type:
    {
        "id": "61603499-6f54-4021-bacf-00e91afe16cb",
        "label": "GENERAL",
        "region_id": null,
        "country_id": "PT",
        "housing_type": "OTH"
    }

Calculate tax:

Copy Code

					
POST https://a.chekin.io/api/v3/tax/calculation/
	Data:
	{
	"country_id": "PT",
	"property_type_id": "61603499-6f54-4021-bacf-00e91afe16cb",
	"location_id": "422149c2-b47a-4656-822a-4de5765bde15",
	"date": "2019-01-01",
	"ages": [10, 13, 20],
	"nights_number": 3
}
Response:
{
    "property_type_id": "61603499-6f54-4021-bacf-00e91afe16cb",
    "date": "2019-01-01",
    "country_id": "PT",
    "location_id": "422149c2-b47a-4656-822a-4de5765bde15",
    "nights_number": 3,
    "tax": 12.0,
    "currency": "EUR",
    "ages": [
        10,
        13,
        20
    ]
}

Use Case SPAIN: Calculate taxes for region Catalonia on property type Hotel 4 Stars

Copy Code

					
 Property type:
	    {
        "id": "675c0357-2226-47c5-8e5c-0f0ba0d30523",
        "label": "5 star hotel, great luxury, luxury camping and establishment or equivalent category equipment",
        "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
        "country_id": "ES",
        "housing_type": "SC1"
    }
 
       Region:
       {
        "id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
        "name": "Catalonia",
        "country_id": "ES"
    }

Calculate tax:

Copy Code

					
       POST https://a.chekin.io/api/v3/tax/calculation/
       Data:
       {
    "property_type_id": "675c0357-2226-47c5-8e5c-0f0ba0d30523",
    "date": "2019-06-01",
    "country_id": "ES",
    "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
    "province_id": "80dd1924-cd74-41c8-b9f2-3b18fe9ecedb",
    "total_people_number": 10,
    "young_people_number": 0,
    "nights_number": 5
     }
     Response:
     {
    "property_type_id": "675c0357-2226-47c5-8e5c-0f0ba0d30523",
    "date": "2019-06-01",
    "country_id": "ES",
    "region_id": "f787d9cc-e474-4c38-9388-cb04f08b67f9",
    "province_id": "80dd1924-cd74-41c8-b9f2-3b18fe9ecedb",
    "total_people_number": 10,
    "young_people_number": 0,
    "nights_number": 5,
    "tax": 112.5,
    "iva": 11.25,
    "total_fee": 123.75,
    "currency": "EUR"
     }

FAQ

Steps for calculating taxes:

Related Articles

Post a Comment Cancel reply

Company

Support

FAQ

CheKin Taxes API

Steps for calculating taxes:

Do you have any question related to this post? Please submit a request!

Related Articles

Post a Comment Cancel reply