swagger: '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
host: toast-api-server
basePath: /authentication/v1
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.
'
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
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\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
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}/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}/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
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\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"
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: 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: 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
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
produces:
- application/json
parameters:
- name: Toast-Restaurant-External-ID
description: The identifier for the restaurant to retrieve orders from.
in: header
required: true
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
type: string
format: ISO-8601
required: false
- 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
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 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
type: string
required: false
responses:
'200':
description: A JSON array of the GUID identifiers for orders.
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
definitions:
RefundTransaction:
allOf:
- $ref: '#/definitions/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.
'
AppliedPackagingInfo:
type: object
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)
'
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
appliedPackagingItems:
type: array
minItems: 1
items:
$ref: '#/definitions/AppliedPackagingItem'
AppliedDiscountTrigger:
type: object
description: The Selection that triggered the application of this discount
properties:
selection:
$ref: '#/definitions/ExternalReference'
quantity:
type: number
format: double
description: The amount of the selection used to trigger the applied discount.
Refund:
type: object
description: A currency amount removed from a guest payment.
properties:
refundAmount:
type: number
format: double
description: The amount of the refund, excluding the tip.
tipRefundAmount:
type: number
format: double
description: The amount of the tip refund.
refundDate:
description: The date and time when the refund was made.
type: string
format: date-time
refundBusinessDate:
x-toast-read-only: true
description: The business date (yyyyMMdd) on which this refund was created. Response only.
type: integer
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: '#/definitions/RefundTransaction'
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
# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast/refs/heads/main/openapi/toast-orders-api-openapi.yml