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.
The Toast platform identifier of the order that you are
adding items to.
checkGuid
required
string
The Toast platform identifier of the check that you are
adding items to.
header Parameters
Toast-Restaurant-External-ID
required
string
The identifier of the restaurant.
Request Body schema: application/json
An array of JSON Selection objects that identify the menu items you are adding.
Array
guid
required
string
The GUID maintained by Toast. Response only.
entityType
required
string
The type of object this is. Response only.
externalId
string
External identifier string that is prefixed by the naming authority. You can use the orders API to set an externalId for an order and then GET the order with that externalId.
required
object (schemas)
A wrapper object containing identifier values for Toast platform entities.
object (schemas)
A wrapper object containing identifier values for Toast platform entities.
object (schemas)
A wrapper object containing identifier values for Toast platform entities.
object (schemas)
A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.
quantity
required
number <double>
Quantity ordered. A decimal number for items sold by weight; a counting number for discrete items.
seatNumber
integer
Indicates which guest seat at a restaurant table ordered
a menu item selection. Restaurant employees can choose the
seat number when they add a menu item to a guest check.
A positive integer value indicates the seat number for
the menu item.
0 - indicates that the menu item is being shared by
multiple guests.
-1 - indicates that the restaurant employee did not
select a seat for the menu item.
Response only.
unitOfMeasure
string
The unit of measure required for weighing the item. Default is NONE, which means the item is not meant to be weighed.
Enum:"NONE""LB""OZ""KG""G"
selectionType
string
Specifies whether this selection is a special request or other off-menu sale. If left null or NONE, describes a normal modifier or item selection.
Enum:"NONE""OPEN_ITEM""SPECIAL_REQUEST""PORTION"
object (schemas)
A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.
Array of objects (schemas) >= 0 items
The itemized discounts applied to this item. Response only.
deferred
boolean
Whether this selection is a deferred revenue transaction, e.g. gift card sales.
preDiscountPrice
number <double>
Gross sale price for this selection. Excludes tax. Response only.
price
number <double>
Net price for this selection. The final price of the item after considering discounts (including discounts at the check level), quantity adjustments, and modifier prices at the time the item was selected for purchase. Response only.
tax
number <double>
The total tax amount for this selection. Response only.
voided
boolean
True if this selection has been voided. Response only.
voidDate
string <date-time>
The date at which this selection was voided. Response only.
voidBusinessDate
integer
The business date (yyyymmdd) on which this selection was voided. Response only.
object (schemas)
A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.
object (RefundDetails)
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.
displayName
string
The display name of the selection. This field can be used to set a special request value, otherwise it will be generated from this Selection's item property.
createdDate
string <date-time>
The date at which this selection was created. Defaults to current time if not specified.
modifiedDate
string <date-time>
The date at which this selection was last modified. Defaults to current time if not specified.
Array of objects (schemas)
A list of modifiers applying to this selection.
fulfillmentStatus
string
Default: "NEW"
Indicates the stage of the preparation workflow that the
menu item selection is in. The fulfillmentStatus of a
menu item selection changes as restaurant employees move
the item through the functions of the Toast POS, for
example order entry and the kitchen display system (KDS).
Response only.
`NEW` - the menu item selection has been added to a
check but has not been sent to the KDS for
preparation.
`HOLD` - a restaurant employee has paused the menu
item selection so that it does not appear in the
KDS for preparation.
`SENT` - the menu item selection has been fired and
appears in the KDS for preparation.
`READY` - preparation is complete, the menu item
selection has been fulfilled and no longer appears in
the KDS. If your restaurant does not use the Toast platform
KDS, items in an order will not reach the `READY`
status.
Enum:"NEW""HOLD""SENT""READY"
taxInclusion
string
Indicates whether the menu item price includes one or more tax
amounts. If the menu item is a modifier for another menu item
selection, it always inherits the tax inclusion behavior of the menu
item it applies to. Values are:
INCLUDED - the menu item price includes one or more tax amounts.
NOT_INCLUDED - the menu item price does not include any tax
amounts.
INHERITED - the menu item is a modifier for another menu item
selection in the check. The taxInclusion value of the parent menu
item selection applies to the modifier. If a menu item selection
that is not a modifier inherits tax inclusion behavior from a
menu or menu group, the taxInclusion value will be either
INCLUDED or NOT_INCLUDED.
Enum:"INCLUDED""NOT_INCLUDED""INHERITED"
Array of objects (schemas)
An array of AppliedTaxRate objects that contain information about tax payments made for the selection. Response only.
object (schemas)
A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.
openPriceAmount
number <double>
A non-negative currency amount that sets the price of a
menu item that is configured to use the Open Price
pricing strategy. If you do not supply an
openPriceAmount value for an open price menu item, the
orders API will set the price to 0.00.
If a menu item is configured to use tax-inclusive
pricing, the orders API calculates the base price and tax
amount based on the open price that you specify. The
open-price amount includes both the base-price and
inclusive tax amount.
This value is write-only. The openPriceAmount is not
present in orders API return data.
receiptLinePrice
number <double>
The price of the menu item selection before any taxes, discounts, and modifier option adjustments are applied.
optionGroupPricingMode
string
Information about how the modifier group affects the pricing of its parent item.
The menu item price that was calculated by the
marketplace facilitator organization that created the
order. POST only. The orders API does not include the
externalPriceAmount value in return data.
Note: you can only include this information if your
Toast API client is associated with a designated
marketplace facilitator organization. Most Toast API
clients do not create marketplace facilitator orders.
Responses
200
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.
400
The request contains data that is not supported by the API.
404
An entity referenced in the order does not exist at the restaurant.
500
An unexpected internal error occurred. There is a requestId attached to this error that can be referenced by the Toast support team.