Toast Tax Rates API

openapi: 3.2.0
info:
  version: 2.5.0
  title: Configuration Tax Rates API
  description: "Returns information about the configuration of a restaurant and \nits menus, such as menu items and alternate payment types, as \nwell as physical configuration such as cash drawers and \nrestaurant tables.\n\nThe configuration API does not return information about entities that you have \nremoved from your restaurant configuration or archived.\n"
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/config/v2
tags:
- name: Tax Rates
paths:
  /taxRates/{guid}:
    get:
      tags:
      - Tax Rates
      operationId: taxRatesGuidGet
      summary: 'Get a tax rate

        '
      description: 'Returns a `TaxRate` object

        containing information about a form of taxation applied to

        sales at a restaurant.

        '
      parameters:
      - name: Toast-Restaurant-External-ID
        description: 'The Toast POS GUID of the restaurant that the configuration

          applies to.

          '
        in: header
        required: true
        schema:
          type: string
      - name: guid
        description: The Toast POS GUID of the tax rate.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a `TaxRate` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxRate'
      security:
      - oauth2:
        - config:read
  /taxRates:
    get:
      tags:
      - Tax Rates
      operationId: taxRatesGet
      summary: 'Get tax rates

        '
      description: 'Returns an array of `TaxRate` objects

        containing information about the forms of taxation applied to

        sales at a restaurant. If a `lastModified` date is

        specified, returns all objects that were created or modified

        after that date.

        '
      parameters:
      - name: Toast-Restaurant-External-ID
        description: 'The Toast POS GUID of the restaurant that the configuration

          applies to.

          '
        in: header
        required: true
        schema:
          type: string
      - name: pageToken
        in: query
        description: "A string that identifies the set of data objects that the \nendpoint will return in its response data. You can use this \nparameter to retrieve one page of response data. You \nget the value that you supply in the `pageToken` parameter \nfrom the `Toast-Next-Page-Token` header field value of a \nprevious request to the endpoint. For more information, see \n<a href=\"https://doc.toasttab.com/doc/devguide/apiResponseDataPagination.html\">Paginating response data</a>.\n"
        schema:
          type: string
      - name: lastModified
        description: 'Limits the return data to objects created or modified after

          a specific date and time. For example:

          `2024-06-20T00:00:00.000%2B0000`.

          '
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Returns an array of `TaxRate` objects.
          headers:
            Toast-Next-Page-Token:
              description: "A string that identifies the following set of objects \nthat the endpoint will return. You can use this value \nto retrieve that page of response data. To return \nthe next page of objects you supply this value in the \n`pageToken` parameter of the next request to the \nendpoint. For more information, see \n<a href=\"https://doc.toasttab.com/doc/devguide/apiResponseDataPagination.html\">Paginating response data</a>.\n\nThe endpoint does not return the \n`Toast-Next-Page-Token` field if there is no following \npage of response data objects. For example, the \nendpoint will not return a `Toast-Next-Page-Token` \nheader field if all the data objects fit in one \nresponse or if you have reached the last page of \nresponse objects.\n"
              schema:
                type: string
          content:
            application/json:
              schema:
                title: Response
                type: array
                minItems: 0
                maxItems: 300
                items:
                  $ref: '#/components/schemas/TaxRate'
      security:
      - oauth2:
        - config:read
components:
  schemas:
    ToastReference:
      type: object
      description: A wrapper object with fields that allow reference to a Toast entity by Toast GUID.
      required:
      - guid
      - entityType
      properties:
        guid:
          description: The GUID maintained by the Toast POS.
          type: string
        entityType:
          description: The type of object this is.
          type: string
    TaxTableRow:
      type: object
      description: A closed sale amount range that corresponds to a specific tax amount in a tax table.
      properties:
        start:
          description: The start of a sale amount range that corresponds to a specific tax amount in a tax table.
          type: number
          format: currency
        end:
          description: The end of a sale amount range that corresponds to a specific tax amount in a tax table.
          type: number
          format: currency
        tax:
          description: The tax amount for the tax table row.
          type: number
          format: currency
        pattern:
          description: Specifies whether the price range is part of an incomplete set of ranges that establish an algorithm that you can use to calculate tax amounts.
          type: boolean
    ConditionalTaxRate:
      type: object
      description: 'A conditional tax rate that overrides the default `rate`

        for a `TaxRate` in

        specific situations. For example, a conditional rate

        might override the default rate when a `TaxRate` is

        applied for a specific dining option, such as takeout.

        '
      properties:
        condition:
          description: A string describing the condition for the tax rate
          type: string
        rate:
          description: The percentage rate of the conditional tax rate
          type: number
          format: double
    TaxRate:
      type: object
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        properties:
          name:
            type: string
            description: The name of this tax rate.
          isDefault:
            type: boolean
            description: True if this tax rate is the default tax rate.
          rate:
            type: number
            format: double
            description: 'The tax rate value.


              For a fixed amount tax rate, is the fixed amount of the tax.


              For a percent tax rate, the percentage is expressed as a decimal value. For example, if the tax rate is 6.25%, then `rate` is 0.0625.


              If `type` is `NONE`, then `rate` is `null`.

              '
          type:
            type: string
            description: The type of the tax rate.
            enum:
            - PERCENT
            - FIXED
            - TABLE
            - NONE
            - EXTERNAL
          roundingType:
            type: string
            description: 'The method used to round fractional currency amounts to non-fractional currency amounts.


              Only applies to `PERCENT` tax rates. For other tax rate types, `roundingType` is `null`.


              Valid values:


              * `HALF_UP` - Round values up or down to the nearest number. If the last digit is 5, which is halfway, then always round up to the nearest number.


              * `HALF_EVEN` - Round values up or down to the nearest number. If the last digit is 5, which is halfway, then round up or down to the nearest even number.


              * `ALWAYS_UP` - Always round up to the next number.


              * `ALWAYS_DOWN` - Always round down to the next number.


              For more details and examples, see <a href="https://doc.toasttab.com/doc/platformguide/adminPercentTaxRates.html#roundingOptions">Rounding options</a>.

              '
            enum:
            - HALF_UP
            - HALF_EVEN
            - ALWAYS_UP
            - ALWAYS_DOWN
          taxTable:
            type: array
            description: An array of `TaxTableRow` objects that define a set of tax amounts that apply to specific sale amount ranges.
            items:
              $ref: '#/components/schemas/TaxTableRow'
          conditionalTaxRates:
            type: array
            description: 'An array of `ConditionalTaxRate`

              objects that indicate the conditional rates that override

              the default `rate` for this `TaxRate` in specific

              situations. For example, a conditional rate might

              override the default rate when a `TaxRate` is applied for

              a specific dining option, such as takeout.

              '
            items:
              $ref: '#/components/schemas/ConditionalTaxRate'
  securitySchemes:
    oauth2:
      description: "Access to Toast APIs, specific endpoints, \nand specific API endpoint operations is \ncontrolled by the scopes that are associated \nwith your API account. \nA full reference for Toast API scopes and \ntheir capabilities can be found in the\n[_Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiScopes.html).\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://toast-api-server/authentication/v1/authentication/login
          scopes:
            config:read: 'Allows reading from the configuration API.

              '