Toast Service Charges API

openapi: 3.2.0
info:
  version: 2.5.0
  title: Configuration Service Charges 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: Service Charges
paths:
  /serviceCharges/{guid}:
    get:
      tags:
      - Service Charges
      operationId: serviceChargesGuidGet
      summary: 'Get a service charge type

        '
      description: 'Returns a `ServiceCharge` object

        containing information about a type of fee applied to

        restaurant sales. For example, an automatic gratuity applied to

        the check for a large dining party might be a type of service

        charge for 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 service charge.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a `ServiceCharge` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceCharge'
      security:
      - oauth2:
        - config:read
  /serviceCharges:
    get:
      tags:
      - Service Charges
      operationId: serviceChargesGet
      summary: 'Get service charges

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

        containing information about the types of fee applied to

        restaurant sales. For example, an automatic gratuity applied to

        the check for a large dining party might be a type of service

        charge for 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 `ServiceCharge` 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/ServiceCharge'
      security:
      - oauth2:
        - config:read
components:
  schemas:
    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
    ServiceCharge:
      type: object
      allOf:
      - $ref: '#/components/schemas/ExternalReference'
      - type: object
        description: Any charge applied to a check for something other than menu item. Typical examples include gratuity and delivery fees.
        properties:
          name:
            type: string
            description: The name of this service charge.
          amountType:
            type: string
            description: The type of service charge.
            enum:
            - FIXED
            - PERCENT
            - OPEN
          amount:
            type: number
            format: double
            description: Amount in USD to be applied for `FIXED` type service charges.
          percent:
            type: number
            format: double
            description: 'Percent fee to be applied for `PERCENT` type service

              charges, based on pre-discount check amount. Must be a

              number between 0 and 100.

              '
          criteria:
            $ref: '#/components/schemas/ServiceChargeCriteria'
          gratuity:
            type: boolean
            description: True if the service charge is a gratuity and is assigned to the owner of the check.
          taxable:
            type: boolean
            description: True if tax should be applied to the service charge.
          applicableTaxes:
            type: array
            description: A reference to the taxes applied to the service charge, if the service charge is taxable.
            items:
              $ref: '#/components/schemas/TaxRate'
          serviceChargeCalculation:
            type: string
            description: Defines whether or not the service charge is applied before (PRE) or after (POST) discounts. This field is null for non-percent service charges.
            enum:
            - PRE_DISCOUNT
            - POST_DISCOUNT
          destination:
            type: string
            description: 'Final recipient of the funds from this service charge.


              * `RESTAURANT` - The business owner of the restaurant receives the service charge funds.

              * `SERVER` - Restaurant employees receive the service charge funds e.g. gratuity.

              * `TOAST` - Toast receives the service charge funds.

              * `THIRD_PARTY` - A third party receives the service charge funds e.g. fundraising funds go to charity.

              '
            enum:
            - RESTAURANT
            - SERVER
            - TOAST
            - THIRD_PARTY
          taxInclusive:
            type: boolean
            description: Supports future functionality.
          taxProrated:
            type: boolean
            description: Supports future functionality.
    ServiceChargeCriteria:
      description: Describes thresholds for when a service charge should be applied to a check.
      properties:
        minCheckAmount:
          type: number
          format: double
          description: The service charge is only applicable if the pre-discount check is at least this amount.
        delivery:
          type: boolean
          description: True if the service charge is only applicable for deliveries.
        maxCheckAmount:
          type: number
          format: double
          description: The service charge is waived if the pre-discount check amount is more than this amount. A `null` value means this criteria is inapplicable.
        minDeliveryDistance:
          type: number
          format: double
          description: The service charge is only applicable to deliveries that are at least this distance. A `null` value means this criteria is inapplicable.
        takeout:
          type: boolean
          description: Indicates whether the service charge is automatically applied to orders that have the takeout dining option behavior.
        dineIn:
          type: boolean
          description: Indicates whether the service charge is applied to orders that have the dine-in dining option behavior.
    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
    ExternalReference:
      type: object
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        properties:
          externalId:
            description: External identifier string, prefixed by the naming authority.
            type: string
        description: A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.
    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
    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.

              '