The Toast Orders API enables retrieval of restaurant orders, checks, and payment information. Supports bulk order queries by date range and individual order retrieval by GUID. Used for building order management, reporting, and delivery integrations.
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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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
/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: [email protected]
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:
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:
dispatchedDate:
deliveryEmployee:
deliveryState:
serviceArea:
curbsidePickupInfo:
numberOfGuests: 1
diningOption:
guid: 18855a26-40d4-4a8f-b484-c6af211dd597
entityType: DiningOption
externalId:
openedDate: 2021-07-30T11:57:46.235+0000
voidBusinessD
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast/refs/heads/main/openapi/toast-orders-openapi.yaml