Toast Discounts API

openapi: 3.2.0
info:
  title: Toast Discounts API
  contact:
    name: Toast developer support
  version: '1.0'
  description: 'Operations tagged Discounts across 2 of this provider''s published API definitions: toast-configuration-openapi.yaml, toast-discounts-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://toast-api-server/config/v2
- url: https://toast-api-server/authentication/v1
tags:
- name: Discounts
paths:
  /discounts/{guid}:
    get:
      tags:
      - Discounts
      operationId: discountsGuidGet
      summary: 'Get a discount

        '
      description: 'Returns a `Discount`

        object containing information about a price deduction

        configured 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 discount.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a `Discount` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
      security:
      - oauth2:
        - config:read
    servers:
    - url: https://toast-api-server/config/v2
  /discounts:
    get:
      tags:
      - Discounts
      operationId: discountsGet
      summary: 'Get discounts

        '
      description: 'Returns an array of `Discount` objects containing

        information about the price deductions configured 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 `Discount` 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/Discount'
      security:
      - oauth2:
        - config:read
    servers:
    - url: https://toast-api-server/config/v2
  /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts:
    post:
      tags:
      - Discounts
      summary: Toast Add Check-level Discounts
      description: 'Adds one or more check-level discounts to a check in an

        existing order. Include an array of `Discount` objects in the

        message body.


        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiDiscountingOrders.html#apiAddingDiscountsToChecks).

        '
      operationId: ordersChecksAppliedDiscountsPost
      parameters:
      - name: orderGuid
        description: 'The Toast platform identifier of the order that you are

          adding a discount to.

          '
        in: path
        required: true
        schema:
          type: string
      - name: checkGuid
        description: 'The Toast platform identifier of the check that you are

          adding a discount to.

          '
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A JSON `Order` object that includes the discount you added.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.discounts:write
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AppliedDiscount'
        description: 'A JSON array of `AppliedDiscount` objects that identify the discounts you are adding.

          '
        required: true
    servers:
    - url: https://toast-api-server/authentication/v1
  /orders/{orderGuid}/checks/{checkGuid}/selections/{selectionGuid}/appliedDiscounts:
    post:
      tags:
      - Discounts
      summary: Toast Add Item-level Discounts
      description: 'Adds one or more item-level discounts to menu item selections

        in a check in an existing order. Include an array of `Discount` objects in the

        message body.


        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiDiscountingOrders.html#apiAddingDiscountsToChecks).

        '
      operationId: ordersChecksSelectionsAppliedDiscountsPost
      parameters:
      - name: orderGuid
        description: 'The Toast platform identifier of the order that you are

          adding a discount to.

          '
        in: path
        required: true
        schema:
          type: string
      - name: checkGuid
        description: 'The Toast platform identifier of the check that you are

          adding a discount to.

          '
        in: path
        required: true
        schema:
          type: string
      - name: selectionGuid
        description: 'The Toast platform identifier of the menu item selection

          that you are adding a discount to.

          '
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A JSON `Order` object that includes the discount you added.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.discounts:write
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AppliedDiscount'
        description: 'A JSON array of `AppliedDiscount` objects that identify the discounts you are adding.

          '
        required: true
    servers:
    - url: https://toast-api-server/authentication/v1
  /applicableDiscounts:
    post:
      tags:
      - Discounts
      summary: Toast Get Applicable Discounts
      description: 'Returns an array of `ApplicableDiscount`

        objects that contain information about the discounts that apply

        to the checks and menu item selections in an order.


        Each `ApplicableDiscount` object contains information that you can

        use to determine which items and checks are eligible for the

        discount.


        If you include a `promoCode` value in the

        `ApplicableDiscount` object, the `applicableDiscounts` endpoint

        returns the only the discounts that are associated with that

        promotional code.

        '
      operationId: applicableDiscountsPost
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A JSON array of `ApplicableDiscount` objects.
          content:
            application/json:
              schema:
                title: ApplicableDiscounts
                type: array
                items:
                  $ref: '#/components/schemas/ApplicableDiscount'
        '400':
          description: Invalid arguments
        '500':
          description: An unexpected internal error occurred. The `requestId` that is attached to this error can be referenced by Toast.
      security:
      - oauth2:
        - orders.orders:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicableDiscountsRequest'
        description: 'A JSON `ApplicableDiscountsRequest` object containing

          information about an order, and an optional `promoCode`.

          '
        required: true
    servers:
    - url: https://toast-api-server/authentication/v1
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
    Discount:
      type: object
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        description: 'A discount configured in Toast Web.

          Discounts are always applied before taxes, but after

          service charges are calculated.

          '
        properties:
          name:
            type: string
            description: The human-readable name of the discount.
          active:
            type: boolean
            description: 'Indicates whether the discount is available and can be

              applied by restaurant employees.

              '
          type:
            type: string
            description: '* `PERCENT` - the discount reduces the price by a

              preconfigured percent.

              * `FIXED` - the discount reduces the price by a

              preconfigured currency amount.

              * `OPEN_PERCENT` - the discount reduces the price by a

              percent entered by a restaurant employee.

              * `OPEN_FIXED` - the discount reduces the price by a

              currency amount entered by a restaurant employee.

              * `BOGO` - a buy one get one (BOGO) discount.

              * `FIXED_TOTAL` - a combo discount that reduces the

              price of all eligible items to a preconfigured currency

              amount.

              '
            enum:
            - PERCENT
            - FIXED
            - OPEN_PERCENT
            - OPEN_FIXED
            - BOGO
            - FIXED_TOTAL
          percentage:
            type: number
            format: double
            description: 'Percent discount applied when the `amountType` is

              `PERCENT`. This value will be greater than 0 and at

              most 100.

              '
          amount:
            type: number
            format: double
            description: 'The currency amount of the discount when the

              `amountType` is `FIXED`. This value will be greater

              than 0.

              '
          selectionType:
            type: string
            description: '* `CHECK` - the discount can be applied to a check.

              * `BOGO` - a buy one get one (BOGO) discount.

              * `ITEM` - the discount can be applied to an item

              selection in a check.

              '
            enum:
            - CHECK
            - ITEM
            - BOGO
          nonExclusive:
            type: boolean
            description: 'Indicates whether you can apply the discount with other

              discounts. This value is always `false` for item and

              combo discounts. Set this value for check and BOGO

              discounts by selecting **Allow with other discounts** in

              the **Discounts Rules** section of the discounts

              configuration page of Toast Web.

              '
          itemPickingPriority:
            type: string
            description: 'Indicates which menu item selections are discounted

              when you apply a BOGO discount. An item that is

              discounted by a BOGO discount is a "get" item.


              * `FIRST` - the BOGO discount applies to the first

              matching item selection in the check or the discount is

              not a BOGO discount.


              * `LEAST_EXPENSIVE` - the BOGO discount applies

              to the least expensive matching item selection in the check.

              `LEAST_EXPENSIVE` is the default `itemPickingPriority` value

              for discounts that are not BOGO discounts.


              * `MOST_EXPENSIVE` - the BOGO discount applies to the most

              expensive matching item selection in the check.

              '
            enum:
            - FIRST
            - LEAST_EXPENSIVE
            - MOST_EXPENSIVE
          fixedTotal:
            type: number
            format: double
            description: 'The total price of items discounted by a combo

              discount. This value is `null` for discounts that are

              not combo discounts.

              '
          promoCodes:
            type: array
            description: 'A list of promotion identifiers associated with this discount.

              '
            items:
              $ref: '#/components/schemas/PromoCode'
    PromoCode:
      type: object
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - type: object
        description: 'Information about a promotion, associated with a discount.

          '
        properties:
          code:
            type: string
            description: The identifier of the promotion. Guests enter the code to apply the discount.
          name:
            type: string
            description: The human-readable name of the promotion.
          usageType:
            type: string
            description: 'Indicates how the promo code can be used.

              * `SINGLE_USE_PHONE` - the promo code can only be used once per phone number. Some promotional discounts require a guest''s phone number when applying the promo code.

              * `SINGLE_USE_UNIQUE_CODE` - the promo code is a unique code that can only be used once.

              * `MULTI_USE` - the promo code can be used multiple times.

              '
            enum:
            - SINGLE_USE_PHONE
            - SINGLE_USE_UNIQUE_CODE
            - MULTI_USE
    RefundTransaction:
      allOf:
      - $ref: '#/components/schemas/ToastReference_2'
      - type: object
        description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

          '
    Device:
      type: object
      description: 'The *Device ID* value that the Toast platform assigns to a specific Toast POS device.


        The `id` value is a unique identifier for a device.


        To find the ID for a Toast POS device, from the overflow  menu (⋮) select *Device Status* and then select the *Device* tab.

        '
      properties:
        id:
          type: string
          description: The physical id of the device
    AppliedDiscountTrigger:
      type: object
      description: The Selection that triggered the application of this discount
      properties:
        selection:
          $ref: '#/components/schemas/ExternalReference'
        quantity:
          type: number
          format: double
          description: The amount of the selection used to trigger the applied discount.
    RefundDetails:
      type: object
      description: 'Information about refunded currency amounts for an item

        selection, modifier option, or service charge. The refund

        information includes separate values for the pre-tax value

        being refunded and the tax amount being refunded.

        '
      properties:
        refundAmount:
          description: 'The value of the menu item or service charge (excluding taxes) being

            refunded. Includes the value of any nested modifier options that

            increased the price of the item or modifier option (an upcharge for

            the modifier option).

            '
          type: number
          format: double
        taxRefundAmount:
          description: 'The tax amount being refunded.

            '
          type: number
          format: double
        refundTransaction:
          description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

            '
          type: object
          $ref: '#/components/schemas/RefundTransaction'
    Order:
      type: object
      description: "A Toast platform order is composed of one or more checks. Each check has \none or more menu item selections.\n\nThe `externalId` value for an order must be unique. If you submit an order\nwith an `externalId` that already exists for another order, the request\nwill fail. You can use this behavior to implement idempotent order\nsubmission by always providing a consistent `externalId` for each unique\norder attempt.\n"
      allOf:
      - $ref: '#/components/schemas/ExternalReference'
      - type: object
        required:
        - diningOption
        - checks
        properties:
          openedDate:
            description: "The business date of the order.\n\nFor dine-in and as soon as possible (ASAP) orders, `openedDate` should match `createdDate`.\n\nFor scheduled orders, `openedDate` should match `promisedDate`.\n\nIf you do not provide a value for \n`openedDate` value when you `POST` a new order, the\nbusiness date of the order is set to the restaurant\nbusiness day that corresponds to the current date and\ntime.\n\nThe business date of an order is affected by the\nbusiness date cutoff time for a restaurant, which is\navailable from the restaurants API in the `closeoutHour` property.\n"
            type: string
            format: date-time
            example: 2025-02-07T08:00:00.000-0800
          modifiedDate:
            type: string
            format: date-time
            description: The most recent date that the order, or a check or menu item selection in the order, was modified.
            example: 2025-02-07T08:00:00.000-0800
          promisedDate:
            description: 'For scheduled orders, the date and time that the order is scheduled to be fulfilled.


              For dine-in and as soon as possible (ASAP) orders, `promisedDate` is `null`.

              '
            type: string
            format: date-time
            example: 2025-05-01T08:00:00.000-0800
          channelGuid:
            description: 'Reserved for future use.

              '
            type: string
            format: uuid
          diningOption:
            description: The restaurant-configured dining option that applies to this order.
            $ref: '#/components/schemas/ExternalReference'
          checks:
            type: array
            description: 'The checks for this order. Most orders have one check.


              If the check is split, then there are multiple checks.

              '
            minItems: 1
            items:
              $ref: '#/components/schemas/Check'
          table:
            type: object
            description: 'The restaurant table at which this order was placed.

              '
            $ref: '#/components/schemas/ExternalReference'
          serviceArea:
            x-toast-read-only: true
            type: object
            description: The service area. Response only.
            $ref: '#/components/schemas/ExternalReference'
          restaurantService:
            x-toast-read-only: true
            type: object
            description: The applicable meal service. For example, lunch or dinner. Response only.
            $ref: '#/components/schemas/ExternalReference'
          revenueCenter:
            type: object
            description: 'The division or section of a restaurant that the order is

              fulfilled in.


              You use revenue centers to analyze financial reporting information.

              '
            $ref: '#/components/schemas/ExternalReference'
          source:
            x-toast-read-only: true
            type: string
            description: 'Indicates the way that the order was placed.


              Valid values:


              * `In Store`

              * `Online`

              * `Order-and-Pay-at-Table`

              * `API`

              * `Kiosk`

              * `Caller Id`

              * `Google`

              * `Invoice`

              * `Toast Pickup App`

              * `Toast Local`

              * `Toast Pay`

              * `Branded Online Ordering`

              * `Catering`

              * `Catering Online Ordering`

              * `Toast Tables`

              * `eCommerce Online ordering`

              * `Branded Mobile App`

              * `Grubhub` (deprecated)


              Response only.

              '
          duration:
            x-toast-read-only: true
            type: integer
            description: The number of seconds between creation and payment. Response only.
          deliveryInfo:
            description: Delivery information related to orders with a `DELIVERY` dining option.
            $ref: '#/components/schemas/DeliveryInfo'
          requiredPrepTime:
            type: string
            format: ISO-8601
            description: "The amount of time that it will take to prepare the order. This value overrides the \ndefault `deliveryPrepTime` or `takeoutPrepTime` that normally controls auto-firing for scheduled orders.\n\nYou can use `requiredPrepTime` to handle atypical orders that will take more time than usual for a restaurant to prepare.\n\nExpress the required preparation time in ISO-8601 duration format. Must be greater than zero and be an \nincrement of five minutes. For example, the value \"PT15M\" sets the required preparation time for the order to 15 minutes.\n"
          estimatedFulfillmentDate:
            x-toast-read-only: true
            type: string
            format: date-time
            description: 'The date and time that the order is expected to be ready for pickup or to be delivered.


              This value is only set when the order dining option uses the `DELIVERY` or `TAKE_OUT` dining behavior. For other dining options, the value is `null`.


              Response only.

              '
            example: 2025-05-01T08:00:00.000-0800
          numberOfGuests:
            type: integer
            description: 'The number of restaurant guests that are associated with the

              order. For example, for a dine-in order, this might be the

              number of guests at a table.

              '
          voided:
            x-toast-read-only: true
            type: boolean
            description: Set to `true` if this order was voided. Response only.
          voidDate:
            x-toast-read-only: true
            type: string
            format: date-time
            description: The date on which this order was voided. Response only.
            example: 2025-02-07T08:00:00.000-0800
          voidBusinessDate:
            x-toast-read-only: true
            type: integer
            description: The business date (yyyyMMdd) on which this order was voided. Response only.
          paidDate:
            type: string
            format: date-time
            description: The most recent date on which this order received payment. If not specified when `POST`ing, it is set to the current system time.
            example: 2025-02-07T08:00:00.000-0800
          closedDate:
            type: string
            format: date-time
            description: 'The most recent date on which the order payment status changed to `CLOSED`.


              This status is not returned for the order. The order is simply `CLOSED` when all of the checks on the order are `CLOSED`.

              '
            example: 2025-02-07T08:00:00.000-0800
          deletedDate:
            type: string
            format: date-time
            description: 'The date and time when the order was deleted.


              The `deletedDate` value only

              applies when the `deleted` value is `true`.


              If `deleted` is `false`, the value

              of `deletedDate` is the UNIX epoch, `1970-01-01T00:00:00.000+0000`.

              '
            example: 2025-02-07T08:00:00.000-0800
          deleted:
            x-toast-read-only: true
            type: boolean
            description: 'Set to `true` if this order is deleted. Response only.


              For example, if you combine a

              check into another order, the original order for the check is deleted.

              '
          businessDate:
            x-toast-read-only: true
            type: integer
            description: The business date (yyyyMMdd) on which the order was fulfilled. Response only.
          server:
            description: The restaurant employee, or server, who is assigned to the order.
            $ref: '#/components/schemas/ExternalReference'
          pricingFeatures:
            type: array
            description: Pricing features that this order is using.
            items:
              type: string
              description: A specific pricing feature used to price out the order.
              enum:
              - TAXESV2
              - TAXESV3
          approvalStatus:
            x-toast-read-only: true
            type: string
            description: 'The current state of the order in the restaurant order

              fulfillment process. For example, the `approvalStatus`

              can indicate that an order is waiting for a restaurant

              employee to approve it or that the order is in a

              restaurant kitchen being fulfilled. Response only.


              Valid values:


              * `NEEDS_APPROVAL` - The order is created but will

              not be fulfilled by the restaurant until an employee

              approves it.


              * `APPROVED` - The order is being fulfilled by the

              restaurant or it was fulfilled in the past. Orders

              remain in this state indefinitely after they are

              fulfilled.


              * `FUTURE` - The order is expected to be fulfilled by the

              restaurant at a future date and time. Restaurant

              employees will receive information about the order at the

              date and time that it is ready to be fulfilled.


              * `NOT_APPROVED` - Restaurant employees received

              information about the order but did not approve it for

              fulfillment. An order enters this state after a period of

              time passes without a restaurant employee approving it.

              '
            enum:
            - NEEDS_APPROVAL
            - APPROVED
            - FUTURE
            - NOT_APPROVED
          createdDevice:
            description: The Toast POS device that created the order. This value is `null` if the order was not created using a Toast POS device.
            $ref: '#/components/schemas/Device'
          createdDate:
            description: The date and time that the Toast platform received the order.
            type: string
            format: date-time
            example: 2025-02-07T08:00:00.000-0800
          lastModifiedDevice:
            description: 'The Toast POS device that modified the order most recently. This value is `null` if the order was never modified using a Toast POS device.


              If the order is modified but the modification was not made using a Toast POS device, this value does not change.

              '
            type: object
            $ref: '#/components/schemas/Device'
          curbsidePickupInfo:
            description: 'Information that the restaurant can use to identify a guest when they arrive outside the restaurant to pick up their order.

              '
            type: object
            $ref: '#/components/schemas/CurbsidePickupInfo'
          marketplaceFacilitatorTaxInfo:
            description: 'Information about the taxes that a marketplace

              facilitator organization remits on behalf of a Toast

              platform restaurant.


              `POST` only. The orders API does not

              include the `marketplaceFacilitatorTaxInfo` value in

              response data.


              **Note**: you can only include this information if your

              Toast API client is associated with a designated

              marketplace facilitator organization. Most Toast API

              clients do not create marketplace facilitator orders.

              '
            type: object
            $ref: '#/components/schemas/MarketplaceFacilitatorTaxInfo'
          createdInTestMode:
            type: boolean
            description: 'Indicates whether the order was created while the restaurant was

              in test mode.


              For more information, see [this _Toast Central_

              article](https://central.toasttab.com/s/article/Test-Mode-Enable-and-Disable-1492802389999)

              '
          appliedPackagingInfo:
            description: 'Information describing the guest''s packaging preferences for this order, for example utensils, napkins, condiments.


              For more information, see [Packaging preferences](https://doc.toasttab.com/doc/devguide/apiOrdersPackagingPreferences.html)

              '
            type: object
            $ref: '#/components/schemas/AppliedPackagingInfo'
          excessFood:
            x-toast-read-only: true
            type: boolean
            description: "Indicates whether the order was created to track excess food (for example, food waste) rather than a \nstandard guest order. Response only.\n\nFor more information on the differences between guest orders and excess food orders, see \n[Daily order for tracking excess food](https://doc.toasttab.com/doc/devguide/apiDailyOrderForTrackingExcessFood.html).\n"
          displayNumber:
            x-toast-read-only: true
            type: string
            description: Response only. Generally starts at one each day and counts up. Not guaranteed to be unique, can be empty if unset.
    ToastReference_2:
      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 platform.
          type: string
        entityType:
          x-toast-read-only: true
          description: The type of object this is. Response only.
          type: string
    AppliedLoyaltyInfo:
      type: object
      description: Information about the customer loyalty program account associated w

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast/refs/heads/main/openapi/toast-discounts-api-openapi.yml