Toast Orders API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Toast Authentication Orders API
  description: 'The authentication API returns an authentication token that you can present

    when your integration client software uses other Toast APIs. For more

    information about authentication, see [the Toast Developer

    Guide](https://doc.toasttab.com/doc/devguide/authentication.html).

    '
  termsOfService: https://pos.toasttab.com/api-terms-of-use
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/authentication/v1
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.

    '
paths:
  /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
      parameters:
      - name: Toast-Restaurant-External-ID
        description: 'The identifier of the restaurant to be used for this price

          calculation.

          '
        in: header
        required: true
        schema:
          type: string
      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.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
        description: 'A _required_ JSON `Order` object containing information about

          the checks, item selections, modifier options, and other parts

          of the order.

          '
        required: true
  /orders/{guid}:
    get:
      tags:
      - Orders
      summary: Toast Get an Order
      description: Retrieves detailed information about a single order, specified by its GUID.
      operationId: ordersGuidGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant where this order was placed.
        in: header
        required: true
        schema:
          type: string
      - name: guid
        description: The GUID for the order to be returned.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A JSON Order object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
  /ordersBulk:
    get:
      tags:
      - Orders
      summary: Toast Get Multiple Orders
      description: "Returns an array of `Order` objects containing detailed\ninformation about all of the orders opened during a period of time.\n\nYou can return the orders for either a specific period of time\nor for one business day.\n\n* Specify both `startDate` and `endDate` to return the orders\n  modified during that period of time.\n\n* Specify the `businessDate` to return the orders promised\n  during that business day.\n"
      operationId: ordersBulkGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: 'The identifier for the restaurant that processed the orders.

          '
        in: header
        required: true
        schema:
          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
        required: false
        schema:
          type: string
          format: ISO-8601
      - 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
        required: false
        schema:
          type: string
          format: ISO-8601
      - 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
        required: false
        schema:
          type: string
      - 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
        required: false
        schema:
          type: integer
      - 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
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: 'A JSON array of `Order` objects for each order processed

            during the period of time that you specify in your request.

            '
          content:
            application/json:
              schema:
                title: Response
                type: array
                items:
                  $ref: '#/components/schemas/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
  /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
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        schema:
          type: string
      - name: orderGuid
        description: 'The Toast platform identifier of the order that you are

          adding items to.

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

          adding items to.

          '
        in: path
        required: true
        schema:
          type: string
      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.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Selection'
        description: 'An array of JSON `Selection` objects that identify the menu items you are adding.

          '
        required: true
  /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.\nYou can use this endpoint to update the delivery time, dispatch time, the\nemployee who is delivering the order, the delivery state, and the delivery notes.\n\nSpecify the Toast platform GUID of the\norder in the `PATCH` path parameters. Returns a JSON\n`Order` object if successful.\n\nOnce an order's `deliveryState` is `DELIVERED`, updates are no longer accepted. \n\nFor more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUpdatingDeliveryInfoForAnOrder.html).\n"
      operationId: ordersOrderGuidDeliveryInfoPatch
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        schema:
          type: string
      - name: orderGuid
        description: 'The Toast platform identifier of the order that you are

          updating the delivery information for.

          '
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success. The response body contains the full order JSON, including information you updated in the `deliveryInfo` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: 'The request contains data that is not supported by the API.

            '
      security:
      - oauth2:
        - orders.delivery_info:write
      requestBody:
        content:
          application/json:
            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.
        description: "A JSON `DeliveryInfo` object\ncontaining the delivery information you want to update for an order.\n\nYou can update any combination of the `deliveredDate`, `dispatchedDate`, `deliveryState`,\n`deliveryEmployee`, or `notes` values. \n\nThese are the only values you can update with this endpoint.\n"
        required: true
  /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
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier of the restaurant.
        in: header
        required: true
        schema:
          type: string
      - name: orderGuid
        in: path
        required: true
        description: The GUID of the order to be voided.
        schema:
          type: string
      responses:
        '200':
          description: Modified order object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: 'Malformed order GUID or other validation errors.

            '
        '404':
          description: Order not found.
      security:
      - oauth2:
        - orders:void
        - orders.channel:void
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                selections:
                  type: object
                  properties:
                    voidAll:
                      type: boolean
                      default: false
                payments:
                  type: object
                  properties:
                    voidAll:
                      type: boolean
                      default: false
  /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
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier for the restaurant where this order was placed.
        in: header
        required: true
        schema:
          type: string
      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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
              example:
                guid: 89488287-f259-435b-a654-0bc391596af0
                entityType: Order
                externalId: null
                revenueCenter: null
                server:
                  guid: c89d1e72-1888-469f-a24b-506c66eafab7
                  entityType: RestaurantUser
                  externalId: null
                lastModifiedDevice:
                  id: null
                source: API
                voidDate: null
                duration: null
                businessDate: 20210730
                paidDate: null
                restaurantService: null
                voided: false
                estimatedFulfillmentDate: 2021-07-30T12:12:46.235+0000
                table: null
                requiredPrepTime: PT15M
                approvalStatus: NEEDS_APPROVAL
                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.
                  deliveredDate: null
                  dispatchedDate: null
                  deliveryEmployee: null
                  deliveryState: null
                serviceArea: null
                curbsidePickupInfo: null
                numberOfGuests: 1
                diningOption:
                  guid: 18855a26-40d4-4a8f-b484-c6af211dd597
                  entityType: DiningOption
                  externalId: null
                openedDate: 2021-07-30T11:57:46.235+0000
                voidBusinessDate: null
                checks:
                - guid: cbcb6fd5-d973-4e44-9b91-2abcee5ea6cd
                  entityType: Check
                  externalId: null
                  displayNumber: pdesjardins-api-1627646263
                  payments:
                  - guid: 88642b2d-c359-4b96-bb8e-9cb3f5c2ac6a
                    entityType: OrderPayment
                    externalId: null
                    originalProcessingFee: null
                    server: null
                    cashDrawer: null
                    lastModifiedDevice:
                      id: null
                    refundStatus: NONE
                    type: OTHER
                    voidInfo: null
                    checkGuid: cbcb6fd5-d973-4e44-9b91-2abcee5ea6cd
                    otherPayment:
                      guid: 0dc19214-d29e-4ab9-a773-27e5812999c7
                      entityType: AlternatePaymentType
                      externalId: null
                    paidDate: 2021-07-30T11:57:46.237+0000
                    orderGuid: 89488287-f259-435b-a654-0bc391596af0
                    cardEntryMode: null
                    paymentStatus: CAPTURED
                    amount: 8.5
                    tipAmount: 0
                    amountTendered: null
                    cardType: null
                    houseAccount: null
                    mcaRepaymentAmount: null
                    createdDevice:
                      id: null
                    paidBusinessDate: 20210730
                    last4Digits: null
                    refund: null
                  appliedDiscounts: []
                  lastModifiedDevice:
                    id: null
                  voidDate: null
                  paidDate: null
                  appliedLoyaltyInfo: null
                  voided: false
                  paymentStatus: OPEN
                  amount: 5
                  tabName: null
                  taxExempt: false
                  openedDate: 2021-07-30T11:57:46.235+0000
                  totalAmount: 5
                  selections:
                  - guid: 2c8b6ece-c503-4f85-aed7-6a8c6526ba0d
                    entityType: MenuItemSelection
                    externalId: null
                    deferred: false
                    preDiscountPrice: 5
                    voidReason: null
                    optionGroup: null
                    displayName: 蟹餅  CRAB CAKES
                    appliedDiscounts: []
                    modifiers: []
                    seatNumber: -1
                    voidDate: null
                    fulfillmentStatus: NEW
                    optionGroupPricingMode: null
                    salesCategory:
                      guid: c0915e46-341e-4ec0-b46e-cb87fab729fd
                      entityType: SalesCategory
                      externalId: null
                    selectionType: NONE
                    price: 5
                    voided: false
                    appliedTaxes: []
                    itemGroup:
                      guid: 881472e6-dd94-48c6-b5c6-25e51a864208
                      entityType: MenuGroup
                      externalId: null
                    item:
                      guid: 9c59d4ab-8242-450f-8f36-b16e1b3ab802
                      entityType: MenuItem
                      externalId: null
                    taxInclusion: NOT_INCLUDED
                    quantity: 1
                    receiptLinePrice: 5
                    unitOfMeasure: NONE
                    refundDetails: null
                    tax: 0
                    diningOption:
                      guid: 18855a26-40d4-4a8f-b484-c6af211dd597
                      entityType: DiningOption
                      externalId: null
                    voidBusinessDate: null
                    createdDate: 2021-07-30T11:57:46.269+0000
                    preModifier: null
                    modifiedDate: 2021-07-30T11:57:46.269+0000
                  voidBusinessDate: null
                  createdDate: 2021-07-30T11:57:46.282+0000
                  deleted: false
                  createdDevice:
                    id: null
                  closedDate: null
                  deletedDate: null
                  modifiedDate: 2021-07-30T11:57:46.282+0000
                  taxAmount: 0
                  appliedServiceCharges: []
                  customer:
                    guid: 970e92e6-33b3-4caa-876b-2c6ef528ef4e
                    entityType: Customer
                    firstName: Severe
                    lastName: Thibault
                    phone: '5555555555'
                    email: severe@example.com
                deleted: false
                createdDevice:
                  id: null
                createdDate: 2021-07-30T11:57:46.286+0000
                closedDate: null
                deletedDate: null
                modifiedDate: 2021-07-30T11:57:46.286+0000
                promisedDate: null
                pricingFeatures:
                - TAXESV2
        '400':
          description: Either the request contains data that is not supported by the current version of the API as described (e.g. specifying credit card as the payment type.), or the order contains an item that is negatively priced.
        '404':
          description: An entity referenced in the order does not exist, or belongs to a restaurant the authenticated 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 header.
        '500':
          description: An unexpected internal error occurred. There is a requestId attached to this error that can be referenced by Toast.
      security:
      - oauth2:
        - orders.orders:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/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.
        description: A JSON object containing information about an order.
        required: true
    get:
      tags:
      - Orders
      summary: Toast Get Order Identifiers (deprecated)
      deprecated: true
      description: "Returns a list of the GUIDs of all orders opened during a period of\ntime. You can return the list of orders for either a period of up to\none hour or for one business day.\n* Specify both `startDate` and `endDate` to return the list of orders\n  modified during a period of up to one hour.\n* Specify the `businessDate` to return the list of orders promised\n  for delivery during a business day.\n"
      operationId: ordersGet
      parameters:
      - name: Toast-Restaurant-External-ID
        description: The identifier for the restaurant to retrieve orders from.
        in: header
        required: true
        schema:
          type: string
      - name: startDate
        description: '\

          The inclusive start date and time. The results exclude orders with an earlier modified date and time.

          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
        required: false
        schema:
          type: string
          format: ISO-8601
      - name: endDate
        description: '

          The exclusive end date and time. The results exclude orders with an equal

          or later modified date and time.


          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
        required: false
        schema:
          type: string
          format: ISO-8601
      - 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 by the restaurant''s business day

          cutoff time, which is available from  the `General` object of the

          restaurants API in the `closeoutHour` property.

          '
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A JSON array of the GUID identifiers for orders.
          content:
            application/json:
              schema:
                title: Response
                type: array
                items:
                  type: string
        '400':
          description: The request contains data that is not supported by the current version of the API as described. For example, specifying credit card as the payment type.
        '500':
          description: An unexpected internal error occurred. The `requestId` that is attached to this error can be referenced by Toast.
      security:
      - oauth2:
        - orders:read
components:
  schemas:
    RefundTransaction:
      allOf:
      - $ref: '#/components/schemas/ToastReference'
      - 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.

          '
    OrderResponse:
      type: object
      properties:
        orders:
          type: array
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/Order'
    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.

   

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