GUguesty
Taxes

Create tax

Create tax configuration with the provided settings.

post/taxes

Request

  • Base URL
    https://open-api.guesty.com/v1
  • URL
    https://open-api.guesty.com/v1/taxes
  • Auth
    API key in header authorization

Request body

unitTypeIdstring
  1. The unit (listing) id on which the new tax will apply.
  2. To apply the tax on account level, leave this field empty.
type'LOCAL_TAX' | 'CITY_TAX' | 'VAT' | 'GOODS_AND_SERVICES_TAX' | 'TOURISM_TAX' | 'OTHER' | 'STATE_TAX' | 'COUNTY_TAX' | 'OCCUPANCY_TAX' | 'TRANSIENT_OCCUPANCY_TAX' | 'HOME_SHARING_TAX' | 'HARMONIZED_SALES_TAX' | 'MINIMUM_ALTERNATE_TAX' required
  1. The tax type.
  2. Multiple taxes of the same type are allowed on the same account/listing level, each represented as a distinct tax entity, but they must have distinct names.
  3. All taxes sharing a type must agree on whether they are inclusive: an inclusive tax cannot be mixed with an exclusive tax of the same type.
  4. Multiple inclusive taxes can share a type only if each has non-overlapping 'appliedOnFees'; 'appliedToAllFees' cannot be 'true' when more than one tax shares the type.
units'PERCENTAGE' | 'FIXED' required

Determines whether the tax amount should be treated as a fixed or percentage value

amountnumber required
  1. the amount of the tax, could be a fixed value or percentage whether units is 'FIXED' or 'PERCENTAGE' respectively.
  2. when 'FIXED' then 'amount' has to be greater then 0
  3. when 'PERCENTAGE' then 'amount' has to be greater then 0 and smaller or equal to 100
quantifier'PER_NIGHT' | 'PER_GUEST' | 'PER_GUEST_PER_NIGHT' | 'PER_STAY' required

Determines by what factor the tax amount will be multiplied

namestring

The name for the tax, which will be used accross guesty. there can be no two taxes with the same name.

appliedToAllFeesboolean
  1. Relevant only when the units equals 'PERCENTAGE'
  2. When equals 'true', then the tax will be calculated on all fees and 'appliedOnFees' must contain all values
appliedOnFeesstring[]
isAppliedByDefaultboolean
  1. When set to 'true' and 'appliedByDefaultOnChannels' is not empty, then Guesty will prededuct the tax from the accommodation fare.
  2. can not be 'true' when 'appliedByDefaultOnChannels' is empty
appliedByDefaultOnChannelsstring[]
isInclusiveboolean
  1. When 'true', the tax amount is included in the accommodation fare rather than added on top.
  2. Cannot be 'true' together with 'isAppliedByDefault', 'appliedByDefaultOnChannels', or 'conditionalOverrides'.

Example request

{
  "unitTypeId": "623892d57f4f56afcb25587c",
  "appliedOnFees": [
    "AF"
  ],
  "appliedByDefaultOnChannels": [
    "airbnb2"
  ],
  "conditionalOverrides": {
    "rules": [
      {
        "dateRange": {
          "from": "12-31",
          "to": "02-01"
        }
      }
    ]
  },
  "channelOverrides": [
    {
      "isAppliedByDefault": true,
      "appliedByDefaultOnChannels": [
        "manual"
      ]
    }
  ]
}

Response

The tax has been successfully created.

_idstring
unitTypeIdstring
accountIdstring required
type'LOCAL_TAX' | 'CITY_TAX' | 'VAT' | 'GOODS_AND_SERVICES_TAX' | 'TOURISM_TAX' | 'OTHER' | 'STATE_TAX' | 'COUNTY_TAX' | 'OCCUPANCY_TAX' | 'TRANSIENT_OCCUPANCY_TAX' | 'HOME_SHARING_TAX' | 'HARMONIZED_SALES_TAX' | 'MINIMUM_ALTERNATE_TAX' required
  1. The tax type.
  2. Multiple taxes of the same type are allowed on the same account/listing level, each represented as a distinct tax entity, but they must have distinct names.
  3. All taxes sharing a type must agree on whether they are inclusive: an inclusive tax cannot be mixed with an exclusive tax of the same type.
  4. Multiple inclusive taxes can share a type only if each has non-overlapping 'appliedOnFees'; 'appliedToAllFees' cannot be 'true' when more than one tax shares the type.
units'PERCENTAGE' | 'FIXED' required
quantifier'PER_NIGHT' | 'PER_GUEST' | 'PER_GUEST_PER_NIGHT' | 'PER_STAY' required
appliedOnFeesstring[] required
appliedByDefaultOnChannelsstring[] required
isInclusiveboolean
  1. When 'true', the tax amount is included in the accommodation fare rather than added on top.
  2. Cannot be 'true' together with 'isAppliedByDefault', 'appliedByDefaultOnChannels', or 'conditionalOverrides'.
isDeletedboolean
amountnumber required
namestring
appliedToAllFeesboolean required
isAppliedByDefaultboolean required

Example response

{
  "_id": "df7hf01cnduhdb2125854dj8",
  "unitTypeId": "623892d57f4f56afcb25587c",
  "accountId": "623892d57f4f56afcb25587c",
  "appliedOnFees": [
    "AF"
  ],
  "channelOverrides": [
    {
      "isAppliedByDefault": true,
      "appliedByDefaultOnChannels": [
        "manual"
      ]
    }
  ],
  "conditionalOverrides": {
    "rules": [
      {
        "dateRange": {
          "from": "12-31",
          "to": "02-01"
        }
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.