---
title: "Create a city tax."
method: POST
path: "/settings/v1/city-tax"
tags: ["CityTax"]
---

# Create a city tax.

`POST /settings/v1/city-tax`

## Request

- Base URL: `https://api.apaleo.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.apaleo.com/settings/v1/city-tax`
- Auth: OAuth 2
  - Implicit: `https://identity.apaleo.com/connect/authorize`
  - Scopes: `settings.manage`, `setup.manage`, `admin`

<br>You must have at least one of these scopes: 'settings.manage, setup.manage'.

## Headers

- `Idempotency-Key` string

## Request body

- CreateCityTaxModel
  - `name` object, required: The name of the city tax, as displayed to guests on invoice, offer, etc. Typical names are city tax or tourist tax.
  - `description` object, required: The description of the city tax, as displayed to guests. Add information on when it applies, and how it is calculated.
  - `propertyId` string, required: The ID of the property for which the city tax is created
  - `type` 'PercentOfGross' | 'PercentOfNet' | 'PerRoomPerNight' | 'PerPersonPerNight' | 'PerPersonPerNightBasedOnNetPrice' | 'PerPersonPerNightBasedOnGrossPrice', required: The base on which the city tax is calculated.
  - `taxHandlingType` 'BeforeTax' | 'AfterTax', required: How to treat the calculated city tax: as before tax or after tax
  - `value` number, double, required: Depending on the type, the percent or multiplier used to calculate city tax
  - `vatType` 'Null' | 'VeryReduced' | 'Reduced' | 'Normal' | 'Without' | 'Special' | 'Special1' | 'Special2' | 'ReducedCovid19' | 'NormalCovid19' | 'Mixed', required: If the city tax is subject to VAT, specify which VAT applies. If not, specify 'Without'.
  - `code` string, nullable: The code for the city tax
  - `priority` integer, nullable: Order in which city taxes should be applied. Lower numbers are applied first. If not provided tax receives priority of existing tax priority + 1, or 1 if no other city tax for this property exists.
  - `includeCityTaxInRateAmount` boolean, nullable: Whether city tax is included in the rate, or added on top of it. Default is `false`
  - `limit` integer, nullable: If set, limits the calculation of the city tax to the specified number of time slices, starting from the beginning. If not set, the city tax will be calculated for the whole stay.
  - `subcategories` CityTaxSubcategoryModel[], nullable: Additional subcategories for different age groups that are eligible for a reduced city tax. Can only be set if the type is 'PerPersonPerNight', 'PercentOfGross', 'PerPersonPerNightBasedOnNetPrice' or 'PerPersonPerNightBasedOnGrossPrice'
    - `name` object, required: The name of the city tax subcategory
    - `value` number, double, required: Fixed value of the tax for this age category
    - `age` CityTaxSubcategoryAgeModel, required
      - `min` integer, required: The minimum age for the age category. The specified value is included in the age range
      - `max` integer, required: The maximum age for the age category. The specified value is included in the age range
  - `pricingRules` CityTaxPricingRuleModel[], nullable: Additional set of rules where you can set a fixed city tax value based on the accommodation cost. Only set if the type is 'PerPersonPerNightBasedOnNetPrice' or 'PerPersonPerNightBasedOnGrossPrice'
    - `value` number, double, required: Fixed value of the tax for the price of up to the MaxPrice
    - `maxPrice` number, double, required: The maximum price this rule applies to (inclusive)
  - `ignoredFor` CityTaxConfigModel[], nullable: The list of rules to define which charges this tax is ignored for
    - `distributionChannel` DistributionChannelTaxConfigModel
      - `channelCode` 'Direct' | 'BookingCom' | 'Ibe' | 'ChannelManager' | 'Expedia' | 'Homelike' | 'Hrs' | 'AltoVita' | 'DesVu' | 'Gimsi', required
      - `sources` string[], nullable
      - `remittanceResponsibility` 'Hotel' | 'Ota', nullable

## Response `201`

City tax successfully created.

- CityTaxCreatedModel
  - `id` string, required: The city tax ID

## Other responses

- `400`: Bad request.
- `401`: You are unauthorized.
- `403`: Forbidden.
- `404`: The Request-URI could not be found.
- `415`: Unsupported media type.
- `422`: Validation errors in the request body or query params.
- `499`: Client closed request.
- `500`: An unexpected error occurred.
- `503`: The server is currently unavailable. Please try later.

---

[API](https://skmtc.dev/apaleo/apis/apaleo-settings-api.md) - [All operations](https://skmtc.dev/apaleo/apis/apaleo-settings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/apaleo/apis/apaleo-settings-api/revisions/da1c3b71ee9a?raw)