> For the complete documentation index, see [llms.txt](https://mobile-calendar.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobile-calendar.gitbook.io/v1/rest-api/local-tax.md).

# Local Tax

Local (tourist/city) tax configuration.

## Get local tax configuration

> Returns the local (tourist/city) tax configuration of the account; 404 when not configured. FIXED: \`adults\` = rate per adult per night, \`children\` = rates per age range, the first \`hotelNights - 1\` nights are free. PERCENTAGE: \`adults\` = percent of the stay price charged once for stays of at least \`hotelNights\` nights. \`includedInPrice\` only marks whether the tax is already included in room prices. Required scope: \`localTax.read\`.

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"local-tax","description":"Local (tourist/city) tax configuration."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"LocalTaxResponse":{"description":"Local tax configuration with metadata","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/LocalTaxEntry"},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"LocalTaxEntry":{"description":"Local (tourist/city) tax configuration — one per account. FIXED: `adults` is the rate per adult per night and `children` gives per-age rates; the first `hotelNights - 1` nights are free, charging starts from night number `hotelNights`. PERCENTAGE: `adults` is a percentage of the stay price charged once, only for stays of at least `hotelNights` nights; children have no separate rate. `includedInPrice` only tells whether the tax is already included in room prices (it does not change the amount). Used in the local tax report and in message templates.","required":["type","adults","children","hotelNights","includedInPrice"],"properties":{"type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"adults":{"description":"Rate per adult per night (FIXED, account currency) or percentage 0–100 (PERCENTAGE).","type":"number","format":"float","minimum":0},"children":{"description":"Child rates by age range; `[]` = children are not charged.","type":"array","items":{"$ref":"#/components/schemas/LocalTaxChildRate"},"maxItems":18},"hotelNights":{"description":"Night from which the tax applies (1 = every night).","type":"integer","maximum":365,"minimum":1},"includedInPrice":{"type":"boolean"}},"type":"object"},"LocalTaxChildRate":{"description":"Child rate for an age range (inclusive, 0–17). Ranges must not overlap.","required":["ageFrom","ageTo","price"],"properties":{"ageFrom":{"type":"integer","maximum":17,"minimum":0},"ageTo":{"description":"Must be ≥ `ageFrom`.","type":"integer","maximum":17,"minimum":0},"price":{"description":"Rate per child per night (FIXED) — ignored for PERCENTAGE. At most 2 decimals.","type":"number","format":"float","minimum":0}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem403":{"description":"Authenticated user but no access.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"403 Forbidden","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem404":{"description":"Resource specified in the request was not found.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"404 Not Found","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]}}},"paths":{"/local-tax":{"get":{"tags":["local-tax"],"summary":"Get local tax configuration","description":"Returns the local (tourist/city) tax configuration of the account; 404 when not configured. FIXED: `adults` = rate per adult per night, `children` = rates per age range, the first `hotelNights - 1` nights are free. PERCENTAGE: `adults` = percent of the stay price charged once for stays of at least `hotelNights` nights. `includedInPrice` only marks whether the tax is already included in room prices. Required scope: `localTax.read`.","operationId":"getLocalTax","responses":{"200":{"description":"Local tax configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalTaxResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem403"}}}},"404":{"description":"Local tax not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem404"}}}}}}}}}
```

## Create or replace local tax configuration

> Creates the configuration (201) or replaces it completely (200). All five fields are required (see LocalTaxUpdateRequest); child age ranges (0–17) must not overlap; for PERCENTAGE all rates must be ≤ 100. Affects future calculations (report, message templates); reservations do not store the tax amount. Required scope: \`localTax.update\`.

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"local-tax","description":"Local (tourist/city) tax configuration."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"LocalTaxUpdateRequest":{"description":"Full configuration (PUT — creates on first use, otherwise replaces). All five fields are required; unknown fields are rejected. For PERCENTAGE, `adults` and every `children[].price` must be ≤ 100.","required":["type","adults","children","hotelNights","includedInPrice"],"properties":{"type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"adults":{"type":"number","format":"float","maximum":99999.99,"minimum":0},"children":{"type":"array","items":{"$ref":"#/components/schemas/LocalTaxChildRate"},"maxItems":18},"hotelNights":{"type":"integer","maximum":365,"minimum":1},"includedInPrice":{"type":"boolean"}},"type":"object"},"LocalTaxChildRate":{"description":"Child rate for an age range (inclusive, 0–17). Ranges must not overlap.","required":["ageFrom","ageTo","price"],"properties":{"ageFrom":{"type":"integer","maximum":17,"minimum":0},"ageTo":{"description":"Must be ≥ `ageFrom`.","type":"integer","maximum":17,"minimum":0},"price":{"description":"Rate per child per night (FIXED) — ignored for PERCENTAGE. At most 2 decimals.","type":"number","format":"float","minimum":0}},"type":"object"},"LocalTaxResponse":{"description":"Local tax configuration with metadata","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/LocalTaxEntry"},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"LocalTaxEntry":{"description":"Local (tourist/city) tax configuration — one per account. FIXED: `adults` is the rate per adult per night and `children` gives per-age rates; the first `hotelNights - 1` nights are free, charging starts from night number `hotelNights`. PERCENTAGE: `adults` is a percentage of the stay price charged once, only for stays of at least `hotelNights` nights; children have no separate rate. `includedInPrice` only tells whether the tax is already included in room prices (it does not change the amount). Used in the local tax report and in message templates.","required":["type","adults","children","hotelNights","includedInPrice"],"properties":{"type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"adults":{"description":"Rate per adult per night (FIXED, account currency) or percentage 0–100 (PERCENTAGE).","type":"number","format":"float","minimum":0},"children":{"description":"Child rates by age range; `[]` = children are not charged.","type":"array","items":{"$ref":"#/components/schemas/LocalTaxChildRate"},"maxItems":18},"hotelNights":{"description":"Night from which the tax applies (1 = every night).","type":"integer","maximum":365,"minimum":1},"includedInPrice":{"type":"boolean"}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem400":{"description":"Request syntax/format error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"400 Bad Request","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem403":{"description":"Authenticated user but no access.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"403 Forbidden","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/local-tax":{"put":{"tags":["local-tax"],"summary":"Create or replace local tax configuration","description":"Creates the configuration (201) or replaces it completely (200). All five fields are required (see LocalTaxUpdateRequest); child age ranges (0–17) must not overlap; for PERCENTAGE all rates must be ≤ 100. Affects future calculations (report, message templates); reservations do not store the tax amount. Required scope: `localTax.update`.","operationId":"updateLocalTax","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalTaxUpdateRequest"}}}},"responses":{"200":{"description":"Updated configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalTaxResponse"}}}},"201":{"description":"Configuration created","headers":{"Location":{"description":"URL of the resource","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalTaxResponse"}}}},"400":{"description":"Bad request (malformed JSON, body is not an object, suspicious content)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem400"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem403"}}}},"422":{"description":"Validation error — e.g. missing field, unknown field, overlapping child age ranges, percentage above 100","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```

## Delete local tax configuration

> Removes the local tax configuration — the tax is no longer calculated for any stay. Required scope: \`localTax.delete\`.

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"local-tax","description":"Local (tourist/city) tax configuration."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem403":{"description":"Authenticated user but no access.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"403 Forbidden","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem404":{"description":"Resource specified in the request was not found.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"404 Not Found","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]}}},"paths":{"/local-tax":{"delete":{"tags":["local-tax"],"summary":"Delete local tax configuration","description":"Removes the local tax configuration — the tax is no longer calculated for any stay. Required scope: `localTax.delete`.","operationId":"deleteLocalTax","responses":{"204":{"description":"Deleted","headers":{"RUID":{"description":"Request unique identifier","schema":{"type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem403"}}}},"404":{"description":"Local tax not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem404"}}}}}}}}}
```