Toast Orders API

swagger: '2.0'
info:
  version: 2.9.0
  title: Toast Orders API
  description: |
    The orders API includes operations that create, update, and retrieve information about restaurant
    guest orders.

    Information on orders includes the checks, items ordered,
    prices, payments, discounts, and customer data.

    You can create a new order. The orders API includes an operation to retrieve the order prices before you `POST` the order.

    You can add items to an existing check.

    The orders API also allows you to retrieve payment information for the order and add a credit card payment to the order.
    You cannot update an existing payment, but you can update the tip amount.

    For delivery orders, you can update the delivery information.

    You can retrieve the applicable discounts for an order, and then add a discount to a menu item selection or a check.

    The orders API supports email addresses that: 
      - Are up to 53 characters long. 
      - Start with the email prefix, ends with the email domain name, where the prefix and domain are separated by an @. 
      - Use the following supported characters:
        - a-z
        - A-Z
        - 0-9
        - _ (underscore)
        - International characters are not supported
  contact:
    name: Toast developer support
host: toast-api-server
basePath: /orders/v2
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Orders
  description: |
    Related to orders made by restaurant guests. For example, a restaurant
    guest orders items from a menu. Toast platform orders include one or
    more guest check.
- name: Payments
  description: |
    Related to guests' payments for restaurant orders. Toast platform
    payments apply to a check in an order.
- name: Discounts
  description: |
    Related to price reduction applied to restaurant orders. For example, a
    restaurant might apply a discount for a promotion.
paths:
  /payments:
    get:
      tags:
      - Payments
      summary: Toast Get Payment Identifiers
      description: |
        Returns a list of the GUIDs for each payment made during
        one restaurant business day.

        The specific hours that make up a business
        day depend on the business day cutoff in the restaurant configuration,
        which is available from the restaurants API in the `closeoutHour`
        property.

        The business day for a restaurant is based on its local time (not UTC
        or local time for an API client).

        You must include one of the
        `paidBusinessDate`, `refundBusinessDate`, or `voidBusinessDate` query
        parameters.
      operationId: paymentsGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The GUID of the restaurant used as the context of the request.
        in: header
        required: true
        type: string
      - name: paidBusinessDate
        description: |
          Returns a list of the payments that were made during
          one business day.

          Specify the business day in the format yyyyMMdd.
          For example, `20170101`.
        in: query
        required: false
        type: string
      - name: refundBusinessDate
        description: |
          Returns a list of the payments that were refunded
          during one business day.

          Specify the business day in the format
          yyyyMMdd. For example, `20170101`.
        in: query
        required: false
        type: string
      - name: voidBusinessDate
        description: |
          Returns a list of the payments that were voided during
          one business day.

          Specify the business day in the format yyyyMMdd.
          For example, `20170101`.
        in: query
        required: false
        type: string
      responses:
        '200':
          description: A JSON array of the GUID identifiers for the payments.
          schema:
            title: Response
            type: array
            items:
              type: string
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payments/{guid}:
    get:
      tags:
      - Payments
      summary: Toast Get a Payment
      description: Returns a JSON `Payment` object containing detailed information about a  single payment, specified by its GUID.
      operationId: paymentsGuidGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The GUID of the restaurant used as the context of the request.
        in: header
        required: true
        type: string
      - name: guid
        description: The GUID for the payment you want to return.
        in: path
        type: string
        required: true
      responses:
        '200':
          description: Returns a JSON `Payment` object.
          schema:
            $ref: '#/definitions/Payment'
        '400':
          description: The GUID was malformed.
        '404':
          description: The specified payment was not found.
      security:
      - oauth2:
        - orders:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /prices:
    post:
      tags:
      - Orders
      summary: Toast Get Order Prices
      description: |
        Calculates the check price amounts, tax amounts, and service
        charges for an `Order` object you supply as a _required message
        body parameter_.

        The `prices` endpoint validates the order you
        submit to ensure all referenced data exists and that you include
        item selections in the expected structure with all required modifier
        options.

        Some values that would be present in the response data when
        creating an order are not present in the response data for the `prices`
        endpoint. For example, the order GUID is not set because the
        Toast platform does not create persistent data for the order.

        The calculated price can change between requests to the
        `prices` endpoint with the same `Order` object if enough time
        passes between the requests. The difference in price is
        possible because the restaurant configuration can change and
        because some pricing configuration is based on time and date
        schedules.
      operationId: pricesPost
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The identifier of the restaurant to be used for this price
          calculation.
        in: header
        required: true
        type: string
      - name: body
        description: |
          A _required_ JSON `Order` object containing information about
          the checks, item selections, modifier options, and other parts
          of the order.
        in: body
        required: true
        schema:
          $ref: '#/definitions/Order'
      responses:
        '200':
          description: |
            Success. The response body contains a JSON `Order` object with
            values for check amounts, taxes, service charges, and other parts
            of the order.

            Because this endpoint only calculates prices,
            no parts of the order persist in the Toast platform. There are no
            GUIDs in the response object.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: |
            Either the request contains data that is not supported by
            the current version of the API as described, or the order
            contains an item that is negatively priced.
        '403':
          description: |
            The API client does not have access to the restaurant, the
            API client does not have the `orders:read` scope, or both.
        '404':
          description: |
            An entity referenced in the order does not exist, or
            belongs to a restaurant that the API client is not
            authorized to access.
        '413':
          description: |
            The number of checks in the submitted order exceeds the limit.
        '415':
          description: |
            The request did not have `application/json` in the
            `Content-Type` HTTP header field.
        '500':
          description: |
            An unexpected internal error occurred. The
            `requestId` that is attached to the error can be referenced by
            the Toast support team.
      security:
      - oauth2:
        - orders.orders:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{guid}:
    get:
      tags:
      - Orders
      summary: Toast Get an Order
      description: Retrieves detailed information about a single order, specified by its GUID.
      operationId: ordersGuidGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant where this order was placed.
        in: header
        required: true
        type: string
      - name: guid
        description: The GUID for the order to be returned.
        in: path
        type: string
        required: true
      responses:
        '200':
          description: A JSON Order object.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: The GUID was malformed.
        '404':
          description: The specified order was not found.
        '500':
          description: There was a problem serializing the order entity.
      security:
      - oauth2:
        - orders:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ordersBulk:
    get:
      tags:
      - Orders
      summary: Toast Get Multiple Orders
      description: |
        Returns an array of `Order` objects containing detailed
        information about all of the orders opened during a period of time.

        You can return the orders for either a specific period of time
        or for one business day.

        * Specify both `startDate` and `endDate` to return the orders
          modified during that period of time.

        * Specify the `businessDate` to return the orders promised
          during that business day.
      operationId: ordersBulkGet
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: |
          The identifier for the restaurant that processed the orders.
        in: header
        required: true
        type: string
      - name: startDate
        description: |
          The inclusive start date and time. The results include orders with a modified
          date and time that occur at or after the `startDate`,
          but before the `endDate`.

          Use ISO-8601 format for the date and time, including a decimal fraction of
          a second. For example, `2016-01-01T14:13:12.000+0400`. URL encode the date
          and time value.

          The date must be after
          2015-12-01T00:00:00.000+0000.
        in: query
        type: string
        format: ISO-8601
        required: false
      - name: endDate
        description: |
          The exclusive end date and time. The results exclude any orders that have
          a modified date and time that occurs at or after `endDate`.

          Use ISO-8601 format for the date and time, including a decimal
          fraction of a second. For example, `2016-01-01T14:13:12.000+0400`. URL
          encode the date and time value.

          The `endDate` date and time
          must be later than the `startDate` parameter value.
        in: query
        type: string
        format: ISO-8601
        required: false
      - name: businessDate
        description: |
          The business date that same-day orders opened or that
          scheduled orders are promised, in the format `yyyymmdd`.

          The business day of an order is determined by the time the
          order is opened or promised in the local time zone, and the
          restaurant's business day cutoff time, which is available
          from  the `General` object of the restaurants API in the
          `closeoutHour` property.
        in: query
        type: string
        required: false
      - name: pageSize
        description: |
          The maximum number of objects to return in the array. If the
          number of objects selected by your request is greater than
          the `pageSize`, the API uses response pagination for the
          remaining objects.

          The maximum `pageSize` is `100`.

          For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiResponseDataPagination.html).
        in: query
        type: integer
        required: false
      - name: page
        description: |
          The sequence number of the set of objects to return in
          paginated response data.

          For example, if you set the
          `pageSize` parameter to `10`, and you set `page` to `2`, the
          API returns a set of objects that starts with the eleventh
          object.

          For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiResponseDataPagination.html).
        in: query
        type: integer
        required: false
      responses:
        '200':
          description: |
            A JSON array of `Order` objects for each order processed
            during the period of time that you specify in your request.
          schema:
            title: Response
            type: array
            items:
              $ref: '#/definitions/Order'
        '400':
          description: |
            The request contains data that is not supported by the API.
        '500':
          description: |
            An unexpected internal error occurred. The
            `requestId` that is attached to this error can be referenced by
            the Toast support team.
      security:
      - oauth2:
        - orders:read
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderGuid}/checks/{checkGuid}/payments:
    post:
      tags:
      - Payments
      summary: Toast Post Payments
      description: |
        Adds one or more payments to a check in an existing order. Include
        information about the payments in an array of `Payment` objects in the
        message body. Specify the Toast platform GUID of the order
        and check in REST path parameters.

        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiAddingPaymentsToACheck.html).
      operationId: ordersChecksPaymentsPost
      produces:
      - application/json
      parameters:
      - name: orderGuid
        description: |
          The Toast platform identifier of the order that you are
          adding payments to.
        in: path
        required: true
        type: string
      - name: checkGuid
        description: |
          The Toast platform identifier of the check that you are
          adding payments to.
        in: path
        required: true
        type: string
      - name: body
        description: |
          An array of JSON `Payment` objects containing information about the payments you are adding.
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/Payment'
      responses:
        '200':
          description: |
            A JSON `Order` object that includes the payments that you added.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.payments:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid}:
    patch:
      tags:
      - Payments
      summary: Toast Update a Tip Amount
      description: |
        Updates the tip amount in an existing payment for a check in an
        order. Include the new `tipAmount` value in a `Payment` object
        in the message body.

        This endpoint does not allow any other
        `Payment` object value for a `PATCH` request.

        Specify the Toast
        platform GUID of the order, check, and payment in REST path
        parameters.

        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUpdatingTipsInAPayment.html).
      operationId: ordersOrderGuidChecksCheckGuidPaymentsPaymentGuidPatch
      produces:
      - application/json
      parameters:
      - name: orderGuid
        description: |
          The Toast platform identifier of the order that you are
          updating a tip in.
        in: path
        required: true
        type: string
      - name: checkGuid
        description: |
          The Toast platform identifier of the check that you are
          updating a tip in.
        in: path
        required: true
        type: string
      - name: paymentGuid
        description: |
          The Toast platform identifier of the payment that you are
          updating a tip in.
        in: path
        required: true
        type: string
      - name: body
        description: |
          A JSON `Payment` object
          containing the `tipAmount` value that will replace any
          existing tip amount for the payment.

          Do not include any
          value other than `tipAmount`.
        in: body
        required: true
        schema:
          $ref: '#/definitions/UpdatePaymentRequest'
      responses:
        '200':
          description: |
            A JSON `Order` object
            that includes the tip amount that you updated.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.payments:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderGuid}/checks/{checkGuid}/selections:
    post:
      tags:
      - Orders
      summary: Toast Add Items to a Check
      description: |
        Adds one or more items to an existing check in an order.

        Include information about the items in an array of `Selection` objects in the
        message body.

        Specify the Toast platform GUID of the order and
        check in REST path parameters.

        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiAddingItemsToACheck.html).
      operationId: ordersOrderGuidChecksCheckGuidSelectionsPost
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        type: string
      - name: orderGuid
        description: |
          The Toast platform identifier of the order that you are
          adding items to.
        in: path
        required: true
        type: string
      - name: checkGuid
        description: |
          The Toast platform identifier of the check that you are
          adding items to.
        in: path
        required: true
        type: string
      - name: body
        description: |
          An array of JSON `Selection` objects that identify the menu items you are adding.
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/Selection'
      responses:
        '200':
          description: |
            Success. The response body contains the full order JSON, including the `Selection` objects with the items from the original check and the newly added ones you included.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: |
            The request contains data that is not supported by the API.
        '404':
          description: |
            An entity referenced in the order does not exist at the restaurant.
        '500':
          description: |
            An unexpected internal error occurred. The `requestId` that is attached to this error can be referenced by the Toast support team.
      security:
      - oauth2:
        - orders.items:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
      produces:
      - application/json
      parameters:
      - name: orderGuid
        description: |
          The Toast platform identifier of the order that you are
          adding a discount to.
        in: path
        required: true
        type: string
      - name: checkGuid
        description: |
          The Toast platform identifier of the check that you are
          adding a discount to.
        in: path
        required: true
        type: string
      - name: body
        description: |
          A JSON array of `AppliedDiscount` objects that identify the discounts you are adding.
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/AppliedDiscount'
      responses:
        '200':
          description: |
            A JSON `Order` object that includes the discount you added.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.discounts:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
      produces:
      - application/json
      parameters:
      - name: orderGuid
        description: |
          The Toast platform identifier of the order that you are
          adding a discount to.
        in: path
        required: true
        type: string
      - name: checkGuid
        description: |
          The Toast platform identifier of the check that you are
          adding a discount to.
        in: path
        required: true
        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
        type: string
      - name: body
        description: |
          A JSON array of `AppliedDiscount` objects that identify the discounts you are adding.
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/AppliedDiscount'
      responses:
        '200':
          description: |
            A JSON `Order` object that includes the discount you added.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: The API cannot process the request.
      security:
      - oauth2:
        - orders.discounts:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderGuid}/deliveryInfo:
    patch:
      tags:
      - Orders
      summary: Toast Update Delivery Information
      description: |
        Updates the delivery information of an order that uses the `DELIVERY` dining option.
        You can use this endpoint to update the delivery time, dispatch time, the
        employee who is delivering the order, the delivery state, and the delivery notes.

        Specify the Toast platform GUID of the
        order in the `PATCH` path parameters. Returns a JSON
        `Order` object if successful.

        Once an order's `deliveryState` is `DELIVERED`, updates are no longer accepted. 

        For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUpdatingDeliveryInfoForAnOrder.html).
      operationId: ordersOrderGuidDeliveryInfoPatch
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        type: string
      - name: orderGuid
        description: |
          The Toast platform identifier of the order that you are
          updating the delivery information for.
        in: path
        required: true
        type: string
      - name: body
        description: |
          A JSON `DeliveryInfo` object
          containing the delivery information you want to update for an order.

          You can update any combination of the `deliveredDate`, `dispatchedDate`, `deliveryState`,
          `deliveryEmployee`, or `notes` values. 

          These are the only values you can update with this endpoint.
        in: body
        required: true
        schema:
          type: object
          properties:
            deliveredDate:
              type: string
              format: date-time
              description: |
                The date on which the order was delivered.
            dispatchedDate:
              type: string
              format: date-time
              description: |
                The date on which the order was dispatched. If `dispatchedDate` is not specified, it is set to the current system time.
            deliveryState:
              type: string
              description: |
                The delivery state of the order.
              enum:
              - PENDING
              - IN_PROGRESS
              - PICKED_UP
              - DELIVERED
            deliveryEmployee:
              type: string
              format: UUID
              description: |
                The Toast platform identifier of the employee who is delivering the order.
            notes:
              type: string
              description: Delivery notes provided by the guest who placed the order. **Writing to this field overwrites the guest’s original notes and may result in the loss of important order information.** Do not replace or remove the guest's notes.
      responses:
        '200':
          description: Success. The response body contains the full order JSON, including information you updated in the `deliveryInfo` object.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: |
            The request contains data that is not supported by the API.
      security:
      - oauth2:
        - orders.delivery_info:write
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderGuid}/void:
    post:
      tags:
      - Orders
      summary: Toast Void an Order
      description: |
        Voids an order, and (if specified) its selections and payments. Only Orders with `OTHER` payment types can be voided.

        A request body that contains the `selections` and `payments` objects with each `voidAll` value set to `true` is required to void an order. The response body is the modified Order object.

        For more information, see [Void an order](https://doc.toasttab.com/doc/devguide/apiVoidOrder.html).
      operationId: voidOrder
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        type: string
      - name: orderGuid
        in: path
        required: true
        type: string
        description: The GUID of the order to be voided.
      - name: body
        in: body
        required: false
        schema:
          type: object
          properties:
            selections:
              type: object
              properties:
                voidAll:
                  type: boolean
                  default: false
            payments:
              type: object
              properties:
                voidAll:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Modified order object.
          schema:
            $ref: '#/definitions/Order'
        '400':
          description: |
            Malformed order GUID or other validation errors.
        '404':
          description: Order not found.
      security:
      - oauth2:
        - orders:void
        - orders.channel:void
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders:
    post:
      tags:
      - Orders
      summary: Toast Post an Order
      description: Submits an order to the server. Returns a JSON `Order` object if successful.
      operationId: ordersPost
      produces:
      - application/json
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier for the restaurant where this order was placed.
        in: header
        required: true
        type: string
      - name: body
        description: A JSON object containing information about an order.
        in: body
        required: true
        schema:
          $ref: '#/definitions/Order'
          example:
            entityType: Order
            diningOption:
              guid: 18855a26-40d4-4a8f-b484-c6af211dd597
              entityType: DiningOption
            marketplaceFacilitatorTaxInfo:
              facilitatorCollectAndRemitTaxOrder: true
            checks:
            - entityType: Check
              displayNumber: pdesjardins-api-1627646263
              selections:
              - entityType: MenuItemSelection
                itemGroup:
                  guid: 881472e6-dd94-48c6-b5c6-25e51a864208
                  entityType: MenuGroup
                item:
                  entityType: MenuItem
                  guid: 9c59d4ab-8242-450f-8f36-b16e1b3ab802
                quantity: 1
                modifiers: []
              customer:
                entityType: Customer
                firstName: Severe
                lastName: Thibault
                phone: 555-555-5555
                email: severe@example.com
              payments:
              - otherPayment:
                  guid: 0dc19214-d29e-4ab9-a773-27e5812999c7
                type: OTHER
                amount: 8.5
                tipAmount: '0'
            deliveryInfo:
              address1: 401 Park Drive
              address2: Suite 801
              city: Boston
              state: MA
              zipCode: '02215'
              latitude: 42.3446671
              longitude: -71.1023575
              notes: Please ring the doorbell.
      responses:
        '200':
          description: A JSON `Order` object that has been persisted in Toast. The returned Order contains generated property values for the check amounts, taxes, service charges, and GUIDs for persisted entities.
          schema:
            $ref: '#/definitions/OrderResponse'
          examples:
            application/json:
              guid: 89488287-f259-435b-a654-0bc391596af0
              entityType: Order
              externalId:
              revenueCenter:
              server:
                guid: c89d1e72-1888-469f-a24b-506c66eafab7
                entityType: RestaurantUser
                externalId:
              lastModifiedDevice:
                id:
              source: API
              voidDate:
              duration:
              businessDate: 20210730
              paidDate:
              restaurantService:
              voided: false
              estimatedFulfillmentDate: 2021-07-30T12:12:46.235+0000
              table:
  

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