Mews Taxations API

openapi: 3.0.4
info:
  title: Mews Booking Engine API (Distributor) Account notes Taxations API
  version: v1
  description: The Mews Booking Engine API (historically the Distributor API, served from /api/distributor/v1) lets developers build guest-facing booking engines that create reservations directly in Mews. It exposes enterprise configuration, availability, pricing, products, vouchers, payment cards, and reservation group creation for front-end client consumption.
  x-generated-from: documentation
  x-source-url: https://api.mews.com/Swagger/distributor/swagger.json
  x-last-validated: '2026-06-02'
servers:
- url: https://api.mews.com
  description: Production
- url: https://api.mews-demo.com
  description: Demo / sandbox
security:
- MewsClientToken: []
  MewsAccessToken: []
tags:
- name: Taxations
paths:
  /api/connector/v1/taxations/getAll:
    post:
      tags:
      - Taxations
      summary: Mews Get All Taxations
      description: Returns all taxations supported in tax environments.
      operationId: taxations_getAll
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Parameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxationResult'
              example:
                Taxations:
                - Code: AT-2020
                  Name: VAT
                  LocalName: MWST
                - Code: AT-2020-Extra
                  Name: Extra tax on top of VAT
                  LocalName: Extra tax on top of MWST
                - Code: AT-2016
                  Name: VAT
                  LocalName: MWST
                - Code: AT
                  Name: VAT
                  LocalName: MWST
                - Code: AW
                  Name: TAX
                  LocalName: TAX
                - Code: CA-QC-2023
                  Name: TVQ/QST
                  LocalName: TVQ/QST
                - Code: PH-MA-CUSTOM
                  Name: Makati local tax
                  LocalName: Makati local tax
                TaxRates:
                - Code: AT-2020-21%
                  TaxationCode: AT
                  Value: 0.21
                  ValidityInvervalsUtc: null
                  Strategy:
                    Discriminator: Relative
                    Value:
                      Value: 0.21
                - Code: AT-2020-Extra-10%
                  TaxationCode: AT-2020-Extra
                  Value: 0.1
                  ValidityInvervalsUtc: null
                  Strategy:
                    Discriminator: Dependent
                    Value:
                      Value: 0.1
                      BaseTaxationCodes:
                      - AT-2020
                - Code: AT-5-EUR
                  TaxationCode: AT
                  Value: 5.0
                  ValidityInvervalsUtc: null
                  Strategy:
                    Discriminator: Flat
                    Value:
                      CurrencyCode: EUR
                      Value: 5.0
                - Code: AW-S
                  TaxationCode: AW
                  Value: 0.2062
                  ValidityInvervalsUtc:
                  - StartUtc: null
                    EndUtc: '2021-01-14T00:00:00Z'
                  Strategy:
                    Discriminator: Relative
                    Value:
                      Value: 0.2062
                - Code: CA-QC-2023-9.975%
                  TaxationCode: CA-QC-2023
                  Value: 0.0
                  ValidityInvervalsUtc:
                  - StartUtc: '2023-10-19T19:00:00Z'
                    EndUtc: null
                  Strategy:
                    Discriminator: Dependent
                    Value:
                      Value: 0.09975
                      BaseTaxationCodes:
                      - CA-QC-MT-LO
                      - CA-QC-LODGING-2023
                      - CA-QC-LO-FLAT
                - Code: PH-MA-CUSTOM-0.75%
                  TaxationCode: PH-MA-CUSTOM
                  Value: 0.0075
                  ValidityInvervalsUtc: null
                  Strategy:
                    Discriminator: Relative
                    Value:
                      Value: 0.0075
        '400':
          description: Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll400Example:
                  summary: Default taxations_getAll 400 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
        '401':
          description: Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll401Example:
                  summary: Default taxations_getAll 401 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
        '403':
          description: Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll403Example:
                  summary: Default taxations_getAll 403 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
        '408':
          description: Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll408Example:
                  summary: Default taxations_getAll 408 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
        '204':
          description: Server has successfully fulfilled the request and there is no additional information to send back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll204Example:
                  summary: Default taxations_getAll 204 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
        '429':
          description: Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll429Example:
                  summary: Default taxations_getAll 429 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
        '500':
          description: Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified, however you can raise an issue through GitHub on our [documentation repository](https://github.com/MewsSystems/gitbook-connector-api).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
              examples:
                TaxationsGetAll500Example:
                  summary: Default taxations_getAll 500 response
                  x-microcks-default: true
                  value:
                    Message: string
                    RequestId: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
                    Details: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    TaxRateStrategyDiscriminator:
      title: Tax rate strategy discriminator
      enum:
      - Relative
      - Flat
      - Dependent
      type: string
      description: ''
      x-enumDescriptions:
      - Used with Relative tax rate strategy (e.g. 21%). Relative tax is calculated only from net base value.
      - Used with Flat tax rate strategy (e.g. 5.00 EUR).
      - Used with Dependent tax rate strategy (e.g. 10%). Dependent tax is calculated from net base value and all taxes it depends on.
    RelativeTaxRateStrategy:
      title: Relative tax rate strategy data
      required:
      - Value
      type: object
      properties:
        Value:
          type: number
          description: Tax rate, e.g. `0.21` in case of 21% tax rate.
          format: double
          example: 100.0
      additionalProperties: false
      x-schema-id: RelativeTaxRateStrategy
    ConnectorApiExceptionResult:
      title: ConnectorApiExceptionResult
      type: object
      properties:
        Message:
          type: string
          nullable: true
          example: string
        RequestId:
          type: string
          nullable: true
          example: 3edd5f9e-7e64-4f2a-9a0e-b3f200e6c111
        Details:
          nullable: true
          example: string
      additionalProperties: false
      x-schema-id: ConnectorApiExceptionResult
    Parameters:
      title: Parameters
      required:
      - AccessToken
      - Client
      - ClientToken
      type: object
      properties:
        ClientToken:
          minLength: 1
          type: string
          description: Token identifying the client application.
          example: string
        AccessToken:
          minLength: 1
          type: string
          description: Access token of the client application.
          example: string
        Client:
          minLength: 1
          type: string
          description: Name and version of the client application.
          example: string
      additionalProperties: false
      x-schema-id: Parameters
    DateTimeIntervalUtc:
      title: DateTimeIntervalUtc
      type: object
      properties:
        StartUtc:
          type: string
          nullable: true
          example: string
        EndUtc:
          type: string
          nullable: true
          example: string
      additionalProperties: false
      x-schema-id: DateTimeIntervalUtc
    DependentTaxRateStrategy:
      title: Dependent tax rate strategy data
      required:
      - BaseTaxationCodes
      - Value
      type: object
      properties:
        Value:
          type: number
          description: Tax rate, e.g. `0.1` in case of 10% tax rate.
          format: double
          example: 100.0
        BaseTaxationCodes:
          type: array
          items:
            type: string
          description: Codes of the taxations that are included in the base of calculation.
      additionalProperties: false
      x-schema-id: DependentTaxRateStrategy
    Taxation:
      title: Taxation
      required:
      - Code
      - LocalName
      - Name
      type: object
      properties:
        Code:
          minLength: 1
          type: string
          description: Code of the taxation.
          example: string
        Name:
          minLength: 1
          type: string
          description: Name of the taxation.
          example: Example Name
        LocalName:
          minLength: 1
          type: string
          description: Local name of the taxation.
          example: Example Name
      additionalProperties: false
      description: Taxation represents set of `TaxRate` within `TaxEnvironment`.
      x-schema-id: Taxation
    TaxRate:
      title: Tax rate
      required:
      - Code
      - Strategy
      - TaxationCode
      type: object
      properties:
        Code:
          minLength: 1
          type: string
          description: Code of the tax rate. To be used when posting revenue items which should be accompanied by the tax rate(s) applicable to the nature of the item and the tax environment.
          example: string
        TaxationCode:
          minLength: 1
          type: string
          description: Code of the `Taxation` the rate is part of.
          example: string
        Value:
          type: number
          description: Tax rate, e.g. `0.21` in case of 21% tax rate.
          format: double
          example: 100.0
        ValidityInvervalsUtc:
          type: array
          items:
            $ref: '#/components/schemas/DateTimeIntervalUtc'
          description: Validity intervals in UTC.
          nullable: true
        Strategy:
          title: Tax rate strategy
          type: object
          properties:
            Discriminator:
              $ref: '#/components/schemas/TaxRateStrategyDiscriminator'
            Value:
              oneOf:
              - $ref: '#/components/schemas/RelativeTaxRateStrategy'
              - $ref: '#/components/schemas/FlatTaxRateStrategy'
              - $ref: '#/components/schemas/DependentTaxRateStrategy'
          description: Tax strategy type, e.g. relative, flat or dependent.
          x-coproduct: true
          x-schema-id: TaxRateStrategyCoproductOfTaxRateStrategyDiscriminator
      additionalProperties: false
      description: Definition of single tax rate.
      x-schema-id: TaxRate
    FlatTaxRateStrategy:
      title: Flat tax rate strategy data
      required:
      - CurrencyCode
      - Value
      type: object
      properties:
        CurrencyCode:
          minLength: 1
          type: string
          description: Code of `Currency`.
          example: EUR
        Value:
          type: number
          description: Absolute value of tax.
          format: double
          example: 100.0
      additionalProperties: false
      x-schema-id: FlatTaxRateStrategy
    TaxationResult:
      title: TaxationResult
      required:
      - Taxations
      - TaxRates
      type: object
      properties:
        Taxations:
          type: array
          items:
            $ref: '#/components/schemas/Taxation'
          description: The supported taxations.
        TaxRates:
          type: array
          items:
            $ref: '#/components/schemas/TaxRate'
          description: The supported tax rates.
      additionalProperties: false
      x-schema-id: TaxationResult
  securitySchemes:
    MewsClientToken:
      type: apiKey
      in: header
      name: ClientToken
      description: Mews authentication is performed by supplying ClientToken, AccessToken and Client as fields in the JSON request body (not as HTTP headers). This securityScheme is a tooling-compatible representation of the ClientToken credential. ClientToken is unique to your application and identifies the API client.
    MewsAccessToken:
      type: apiKey
      in: header
      name: AccessToken
      description: Tooling-compatible representation of the AccessToken credential, which is supplied in the JSON request body. AccessToken is unique to the connection with a property (enterprise) and identifies the property or properties whose data and services you can access. Portfolio Access Tokens enable multi-property access with a single token.