{
  "swagger": "2.0",
  "info": {
    "title": "apaleo Taxes API - not safe for work",
    "description": "Continuously evolving version - use at your own risk! Tax engine configuration.",
    "version": "v0-nsfw"
  },
  "paths": {
    "/taxes/v0-nsfw/tax-definitions": {
      "post": {
        "tags": [
          "TaxDefinition"
        ],
        "summary": "Create a tax definition.",
        "description": "Create a new tax definition.\u003Cbr\u003EYou must have this scope: \u0027admin\u0027.\u003Cbr\u003EFor fine-grained clients, you must have this permission: \u0027core.tax_definitions.create\u0027.",
        "operationId": "TaxesTax-definitionsPost",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "description": "Unique key for safely retrying requests without accidentally performing the same operation twice. \nWe\u0027ll always send back the same response for requests made with the same key, \nand keys can\u0027t be reused with different request parameters. Keys expire after 24 hours.",
            "type": "string"
          },
          {
            "in": "body",
            "name": "body",
            "description": "The definition of the tax.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CreateTaxDefinitionModel"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Tax definition successfully created.",
            "schema": {
              "$ref": "#/definitions/TaxDefinitionCreatedModel"
            },
            "headers": {
              "Location": {
                "description": "The location of the created resource.",
                "type": "string"
              }
            }
          },
          "404": {
            "description": "The Request-URI could not be found."
          },
          "415": {
            "description": "Unsupported media type."
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "You are unauthorized."
          },
          "403": {
            "description": "Forbidden."
          },
          "499": {
            "description": "Client closed request."
          },
          "500": {
            "description": "An unexpected error occurred."
          },
          "503": {
            "description": "The server is currently unavailable. Please try later."
          },
          "422": {
            "description": "Validation errors in the request body or query params.",
            "schema": {
              "$ref": "#/definitions/MessageItemCollection"
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "admin"
            ]
          }
        ]
      },
      "get": {
        "tags": [
          "TaxDefinition"
        ],
        "summary": "Get all tax definitions.",
        "description": "Get a list of tax definitions, optionally filtered by property.\u003Cbr\u003EYou must have this scope: \u0027admin\u0027.\u003Cbr\u003EFor fine-grained clients, you must have this permission: \u0027core.tax_definitions.read\u0027.",
        "operationId": "TaxesTax-definitionsGet",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "propertyIds",
            "description": "Filter by the specified property ids",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "schema": {
              "$ref": "#/definitions/TaxDefinitionListModel"
            }
          },
          "204": {
            "description": "No tax definitions found."
          },
          "404": {
            "description": "The Request-URI could not be found."
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "You are unauthorized."
          },
          "403": {
            "description": "Forbidden."
          },
          "499": {
            "description": "Client closed request."
          },
          "500": {
            "description": "An unexpected error occurred."
          },
          "503": {
            "description": "The server is currently unavailable. Please try later."
          },
          "422": {
            "description": "Validation errors in the request body or query params.",
            "schema": {
              "$ref": "#/definitions/MessageItemCollection"
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "admin"
            ]
          }
        ]
      }
    },
    "/taxes/v0-nsfw/tax-definitions/{id}": {
      "get": {
        "tags": [
          "TaxDefinition"
        ],
        "summary": "Get a specific tax definition.",
        "description": "Get a specific tax definition by its id.\u003Cbr\u003EYou must have this scope: \u0027admin\u0027.\u003Cbr\u003EFor fine-grained clients, you must have this permission: \u0027core.tax_definitions.read\u0027.",
        "operationId": "TaxesTax-definitionsByIdGet",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "description": "The id of the tax definition.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "schema": {
              "$ref": "#/definitions/TaxDefinitionModel"
            }
          },
          "404": {
            "description": "The Request-URI could not be found."
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "You are unauthorized."
          },
          "403": {
            "description": "Forbidden."
          },
          "499": {
            "description": "Client closed request."
          },
          "500": {
            "description": "An unexpected error occurred."
          },
          "503": {
            "description": "The server is currently unavailable. Please try later."
          },
          "422": {
            "description": "Validation errors in the request body or query params.",
            "schema": {
              "$ref": "#/definitions/MessageItemCollection"
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "admin"
            ]
          }
        ]
      },
      "patch": {
        "tags": [
          "TaxDefinition"
        ],
        "summary": "Patch a tax definition.",
        "description": "Patch a specific tax definition by its id using JSON Patch.\nHere is the list of operations that are currently allowed:\n- Replace name\n- Replace description\n- Replace vatType\n- Replace vatHandlingType\n- Replace applicability\n- Replace, add, or remove calculationRules\u003Cbr\u003EYou must have this scope: \u0027admin\u0027.\u003Cbr\u003EFor fine-grained clients, you must have this permission: \u0027core.tax_definitions.modify\u0027.",
        "operationId": "TaxesTax-definitionsByIdPatch",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "description": "The id of the tax definition.",
            "required": true,
            "type": "string"
          },
          {
            "in": "body",
            "name": "body",
            "description": "The JSON Patch operations to apply.",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Operation"
              }
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Tax definition successfully patched."
          },
          "404": {
            "description": "The Request-URI could not be found."
          },
          "415": {
            "description": "Unsupported media type."
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "You are unauthorized."
          },
          "403": {
            "description": "Forbidden."
          },
          "499": {
            "description": "Client closed request."
          },
          "500": {
            "description": "An unexpected error occurred."
          },
          "503": {
            "description": "The server is currently unavailable. Please try later."
          },
          "422": {
            "description": "Validation errors in the request body or query params.",
            "schema": {
              "$ref": "#/definitions/MessageItemCollection"
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "admin"
            ]
          }
        ]
      },
      "delete": {
        "tags": [
          "TaxDefinition"
        ],
        "summary": "Delete a tax definition.",
        "description": "Hard delete a specific tax definition by its id.\u003Cbr\u003EYou must have this scope: \u0027admin\u0027.\u003Cbr\u003EFor fine-grained clients, you must have this permission: \u0027core.tax_definitions.delete\u0027.",
        "operationId": "TaxesTax-definitionsByIdDelete",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "description": "The id of the tax definition.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "204": {
            "description": "Tax definition successfully deleted."
          },
          "404": {
            "description": "The Request-URI could not be found."
          },
          "400": {
            "description": "Bad request."
          },
          "401": {
            "description": "You are unauthorized."
          },
          "403": {
            "description": "Forbidden."
          },
          "499": {
            "description": "Client closed request."
          },
          "500": {
            "description": "An unexpected error occurred."
          },
          "503": {
            "description": "The server is currently unavailable. Please try later."
          },
          "422": {
            "description": "Validation errors in the request body or query params.",
            "schema": {
              "$ref": "#/definitions/MessageItemCollection"
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "admin"
            ]
          }
        ]
      }
    }
  },
  "definitions": {
    "CreateTaxDefinitionModel": {
      "type": "object",
      "required": [
        "applicability",
        "calculationRules",
        "classification",
        "code",
        "description",
        "name",
        "propertyId",
        "vatHandlingType",
        "vatType"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "The code of the tax definition."
        },
        "propertyId": {
          "type": "string",
          "description": "The id of the property this tax definition belongs to."
        },
        "name": {
          "type": "object",
          "description": "The name of the tax definition, as displayed to guests on folio, invoice, etc.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "description": {
          "type": "object",
          "description": "The description of the tax definition.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "classification": {
          "type": "string",
          "description": "The classification of the tax definition. Immutable after creation.",
          "enum": [
            "LocalTax",
            "ConsumptionTax"
          ]
        },
        "vatType": {
          "type": "string",
          "description": "The VAT type that applies to this tax definition. Set to \u0027Without\u0027 if no VAT applies.",
          "enum": [
            "Null",
            "VeryReduced",
            "Reduced",
            "Normal",
            "Without",
            "Special",
            "Special1",
            "Special2",
            "ReducedCovid19",
            "NormalCovid19",
            "Mixed"
          ]
        },
        "vatHandlingType": {
          "type": "string",
          "description": "Whether VAT is included in or excluded from calculated tax amount.",
          "enum": [
            "Excluded",
            "Included"
          ]
        },
        "applicability": {
          "$ref": "#/definitions/TaxApplicabilityModel"
        },
        "calculationRules": {
          "type": "array",
          "description": "Rules that define how the tax amount is calculated.\nOnly one rule is considered for calculation based on the order value of the rule and filters.",
          "items": {
            "$ref": "#/definitions/TaxCalculationRuleModel"
          }
        }
      },
      "additionalProperties": false,
      "example": {
        "code": "ALCOHOL",
        "propertyId": "MUC",
        "name": {
          "en": "Alcohol tax"
        },
        "description": {
          "en": "Alcohol tax description"
        },
        "classification": "ConsumptionTax",
        "vatType": "Reduced",
        "vatHandlingType": "Included",
        "applicability": {
          "appliedTo": {
            "services": [
              {
                "serviceType": "FoodAndBeverages",
                "subAccountIds": [
                  "ALCOHOL"
                ]
              }
            ]
          }
        },
        "calculationRules": [
          {
            "validityPeriod": {
              "from": "2025-06-01",
              "to": "2025-08-31"
            },
            "stayDayIndexRange": {
              "from": 0,
              "to": 10
            },
            "priority": 0,
            "order": 1,
            "calculationKind": "Percent",
            "calculationBase": "Gross",
            "calculation": {
              "type": "PerService",
              "perService": {
                "value": 7.5
              }
            }
          }
        ]
      }
    },
    "DayIndexRangeModel": {
      "type": "object",
      "required": [
        "from"
      ],
      "properties": {
        "from": {
          "type": "integer",
          "description": "The zero-based start day index of the stay. For example, 0 means the first night.",
          "format": "int32",
          "maximum": 2147483647,
          "minimum": 0
        },
        "to": {
          "type": "integer",
          "description": "The zero-based end day index of the stay (inclusive). If not set, the rule applies from \u0027From\u0027 onwards.",
          "format": "int32",
          "maximum": 2147483647,
          "minimum": 0,
          "x-nullable": true
        }
      },
      "additionalProperties": false
    },
    "MessageItemCollection": {
      "type": "object",
      "properties": {
        "messages": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "readOnly": true,
          "x-nullable": true
        }
      },
      "additionalProperties": false
    },
    "Operation": {
      "type": "object",
      "properties": {
        "value": {
          "x-nullable": true
        },
        "path": {
          "type": "string",
          "x-nullable": true
        },
        "op": {
          "type": "string",
          "x-nullable": true
        },
        "from": {
          "type": "string",
          "x-nullable": true
        }
      },
      "additionalProperties": false
    },
    "PerServiceTaxCalculationModel": {
      "type": "object",
      "required": [
        "value"
      ],
      "properties": {
        "value": {
          "type": "number",
          "description": "The value of tax applied once per service (e.g. percentage or fixed amount depending on CalculationKind).",
          "format": "double"
        }
      },
      "additionalProperties": false
    },
    "TaxApplicabilityModel": {
      "type": "object",
      "required": [
        "appliedTo"
      ],
      "properties": {
        "appliedTo": {
          "$ref": "#/definitions/TaxApplicabilityScopeModel"
        }
      },
      "additionalProperties": false
    },
    "TaxApplicabilityScopeModel": {
      "type": "object",
      "required": [
        "services"
      ],
      "properties": {
        "services": {
          "type": "array",
          "description": "The list of service filters that determine which services this tax applies to.",
          "items": {
            "$ref": "#/definitions/TaxableServiceFilterModel"
          }
        }
      },
      "additionalProperties": false
    },
    "TaxCalculationModel": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of calculation.",
          "enum": [
            "PerService"
          ]
        },
        "perService": {
          "$ref": "#/definitions/PerServiceTaxCalculationModel"
        }
      },
      "additionalProperties": false
    },
    "TaxCalculationRuleModel": {
      "type": "object",
      "required": [
        "calculation",
        "calculationBase",
        "calculationKind",
        "order"
      ],
      "properties": {
        "validityPeriod": {
          "$ref": "#/definitions/ValidityPeriodModel"
        },
        "stayDayIndexRange": {
          "$ref": "#/definitions/DayIndexRangeModel"
        },
        "priority": {
          "type": "integer",
          "description": "The priority of this rule.\nThis is now unused in favor of Order. In case of multiple rules it would determine the order of application, the rule with the highest value of priority was considered. - \u003Cb\u003EDEPRECATED: Priority is deprecated, use Order instead\u003C/b\u003E",
          "format": "int32"
        },
        "order": {
          "type": "integer",
          "description": "The order of this rule.\nIn case of multiple rules match the conditions, the rule with the lowest value of order is considered.",
          "format": "int32"
        },
        "calculationKind": {
          "type": "string",
          "description": "The kind of calculation.",
          "enum": [
            "Percent",
            "FixedAmount"
          ]
        },
        "calculationBase": {
          "type": "string",
          "description": "The tax base used for calculation.",
          "enum": [
            "Net",
            "Gross"
          ]
        },
        "calculation": {
          "$ref": "#/definitions/TaxCalculationModel"
        }
      },
      "additionalProperties": false
    },
    "TaxDefinitionCreatedModel": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The id of the created tax definition."
        }
      },
      "additionalProperties": false
    },
    "TaxDefinitionListItemModel": {
      "type": "object",
      "required": [
        "classification",
        "code",
        "description",
        "id",
        "name",
        "propertyId",
        "vatHandlingType",
        "vatType"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The id of the tax definition."
        },
        "code": {
          "type": "string",
          "description": "The code of the tax definition."
        },
        "propertyId": {
          "type": "string",
          "description": "The id of the property this tax definition belongs to."
        },
        "name": {
          "type": "string",
          "description": "The name of the tax definition, as displayed to guests on folio, invoice, etc.",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "description": "The description of the tax definition.",
          "minLength": 1
        },
        "classification": {
          "type": "string",
          "description": "The classification of the tax definition.",
          "enum": [
            "LocalTax",
            "ConsumptionTax"
          ]
        },
        "vatType": {
          "type": "string",
          "description": "The VAT type that applies to this tax definition. Set to \u0027Without\u0027 if no VAT applies.",
          "enum": [
            "Null",
            "VeryReduced",
            "Reduced",
            "Normal",
            "Without",
            "Special",
            "Special1",
            "Special2",
            "ReducedCovid19",
            "NormalCovid19",
            "Mixed"
          ]
        },
        "vatHandlingType": {
          "type": "string",
          "description": "Whether VAT is included in or excluded from calculated tax amount.",
          "enum": [
            "Excluded",
            "Included"
          ]
        }
      },
      "additionalProperties": false
    },
    "TaxDefinitionListModel": {
      "type": "object",
      "required": [
        "count",
        "taxDefinitions"
      ],
      "properties": {
        "taxDefinitions": {
          "type": "array",
          "description": "List of tax definitions",
          "items": {
            "$ref": "#/definitions/TaxDefinitionListItemModel"
          }
        },
        "count": {
          "type": "integer",
          "description": "Total count of items",
          "format": "int64"
        }
      },
      "additionalProperties": false,
      "example": {
        "taxDefinitions": [
          {
            "id": "MUC-ALCOHOL",
            "code": "ALCOHOL",
            "propertyId": "MUC",
            "name": "Alcohol tax",
            "description": "Tax on alcoholic beverages",
            "classification": "ConsumptionTax",
            "vatType": "Reduced",
            "vatHandlingType": "Included"
          }
        ],
        "count": 1
      }
    },
    "TaxDefinitionModel": {
      "type": "object",
      "required": [
        "applicability",
        "calculationRules",
        "classification",
        "code",
        "description",
        "id",
        "name",
        "propertyId",
        "vatHandlingType",
        "vatType"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The id of the tax definition."
        },
        "code": {
          "type": "string",
          "description": "The code of the tax definition."
        },
        "propertyId": {
          "type": "string",
          "description": "The id of the property this tax definition belongs to."
        },
        "name": {
          "type": "object",
          "description": "The name of the tax definition, as displayed to guests on folio, invoice, etc.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "description": {
          "type": "object",
          "description": "The description of the tax definition.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "classification": {
          "type": "string",
          "description": "The classification of the tax definition.",
          "enum": [
            "LocalTax",
            "ConsumptionTax"
          ]
        },
        "vatType": {
          "type": "string",
          "description": "The VAT type that applies to this tax definition. Set to \u0027Without\u0027 if no VAT applies.",
          "enum": [
            "Null",
            "VeryReduced",
            "Reduced",
            "Normal",
            "Without",
            "Special",
            "Special1",
            "Special2",
            "ReducedCovid19",
            "NormalCovid19",
            "Mixed"
          ]
        },
        "vatHandlingType": {
          "type": "string",
          "description": "Whether VAT is included in or excluded from calculated tax amount.",
          "enum": [
            "Excluded",
            "Included"
          ]
        },
        "applicability": {
          "$ref": "#/definitions/TaxApplicabilityModel"
        },
        "calculationRules": {
          "type": "array",
          "description": "Rules that define how the tax amount is calculated.\nOnly one rule is considered for calculation based on the order value of the rule and filters.",
          "items": {
            "$ref": "#/definitions/TaxCalculationRuleModel"
          }
        }
      },
      "additionalProperties": false,
      "example": {
        "id": "MUC-ALCOHOL",
        "code": "ALCOHOL",
        "propertyId": "MUC",
        "name": {
          "en": "Alcohol tax"
        },
        "description": {
          "en": "Alcohol tax description"
        },
        "classification": "ConsumptionTax",
        "vatType": "Reduced",
        "vatHandlingType": "Included",
        "applicability": {
          "appliedTo": {
            "services": [
              {
                "serviceType": "FoodAndBeverages",
                "subAccountIds": [
                  "ALCOHOL"
                ]
              }
            ]
          }
        },
        "calculationRules": [
          {
            "validityPeriod": {
              "from": "2025-06-01",
              "to": "2025-08-31"
            },
            "stayDayIndexRange": {
              "from": 0,
              "to": 10
            },
            "priority": 0,
            "order": 1,
            "calculationKind": "Percent",
            "calculationBase": "Gross",
            "calculation": {
              "type": "PerService",
              "perService": {
                "value": 7.5
              }
            }
          }
        ]
      }
    },
    "TaxableServiceFilterModel": {
      "type": "object",
      "required": [
        "serviceType"
      ],
      "properties": {
        "serviceType": {
          "type": "string",
          "description": "The type of service this filter applies to.",
          "enum": [
            "Other",
            "Accommodation",
            "FoodAndBeverages",
            "CancellationFees",
            "NoShow"
          ]
        },
        "subAccountIds": {
          "type": "array",
          "description": "The sub-account ids this filter is restricted to. A missing or null\nlist means the filter applies regardless of the service\u0027s sub-account\n(equivalent to an empty list).",
          "items": {
            "type": "string"
          },
          "x-nullable": true
        }
      },
      "additionalProperties": false
    },
    "ValidityPeriodModel": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "The start date of the validity period. If not set, the rule is valid from the beginning of time.",
          "format": "date",
          "example": "2020-10-10",
          "x-nullable": true
        },
        "to": {
          "type": "string",
          "description": "The end date of the validity period. If not set, the rule is valid indefinitely.",
          "format": "date",
          "example": "2020-10-10",
          "x-nullable": true
        }
      },
      "additionalProperties": false
    }
  },
  "securityDefinitions": {
    "oauth2": {
      "type": "oauth2",
      "flow": "implicit",
      "authorizationUrl": "https://identity.apaleo.com/connect/authorize",
      "scopes": {
        "admin": "Full access",
        "reservations.import": "Import reservations"
      }
    }
  },
  "tags": [
    {
      "name": "TaxDefinition"
    }
  ]
}