Mews Taxations API

openapi: 3.0.4
info:
  title: Connector Account notes Taxations API
  description: General-purpose API that enables partners of Mews to access data and services in Mews Operations
  termsOfService: https://www.mews.com/en/terms-conditions/partners
  contact:
    name: Partner success
    email: partnersuccess@mews.com
  version: v1
servers:
- url: https://api.mews.com
tags:
- name: Taxations
paths:
  /api/connector/v1/taxations/getAll:
    post:
      tags:
      - Taxations
      summary: 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'
        '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'
        '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'
        '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'
        '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'
        '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'
        '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'
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.
    ConnectorApiExceptionResult:
      title: ConnectorApiExceptionResult
      type: object
      properties:
        Message:
          type: string
          nullable: true
        RequestId:
          type: string
          nullable: true
        Details:
          nullable: true
      additionalProperties: false
      x-schema-id: ConnectorApiExceptionResult
    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
      additionalProperties: false
      x-schema-id: RelativeTaxRateStrategy
    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
        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.
        Name:
          minLength: 1
          type: string
          description: Name of the taxation.
        LocalName:
          minLength: 1
          type: string
          description: Local name of the taxation.
      additionalProperties: false
      description: Taxation represents set of `TaxRate` within `TaxEnvironment`.
      x-schema-id: Taxation
    FlatTaxRateStrategy:
      title: Flat tax rate strategy data
      required:
      - CurrencyCode
      - Value
      type: object
      properties:
        CurrencyCode:
          minLength: 1
          type: string
          description: Code of `Currency`.
        Value:
          type: number
          description: Absolute value of tax.
          format: double
      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
    DateTimeIntervalUtc:
      title: DateTimeIntervalUtc
      type: object
      properties:
        StartUtc:
          type: string
          nullable: true
        EndUtc:
          type: string
          nullable: true
      additionalProperties: false
      x-schema-id: DateTimeIntervalUtc
    Parameters:
      title: Parameters
      required:
      - AccessToken
      - Client
      - ClientToken
      type: object
      properties:
        ClientToken:
          minLength: 1
          type: string
          description: Token identifying the client application.
        AccessToken:
          minLength: 1
          type: string
          description: Access token of the client application.
        Client:
          minLength: 1
          type: string
          description: Name and version of the client application.
      additionalProperties: false
      x-schema-id: Parameters
    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.
        TaxationCode:
          minLength: 1
          type: string
          description: Code of the `Taxation` the rate is part of.
        Value:
          type: number
          description: Tax rate, e.g. `0.21` in case of 21% tax rate.
          format: double
        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