Add items to a check

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.

Securityoauth2
Request
path Parameters
checkGuid
required
string

The Toast platform identifier of the check that you are adding items to.

orderGuid
required
string

The Toast platform identifier of the order 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
Array of objects (AppliedDiscount) >= 0 items

The itemized discounts that are applied to this item. Response only.

Array of objects (AppliedTaxRate)

An array of AppliedTaxRate objects that contain information about tax payments made for the selection. Response only.

createdDate
string <date-time>

The date on which this selection was created. If not specified, defaults to the current time.

deferred
boolean

Whether this selection is a deferred revenue transaction, such as a gift card sale.

object (ExternalReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

displayName
string

The display name of the selection.

Can be used to set a special request value.

Otherwise, it is generated from this selection's item property.

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.

externalPriceAmount
number <double>

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. It is used to populate receiptLinePrice.

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.

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.

Valid values:

  • NEW - The menu item selection was added to a check but is not yet sent to the KDS for preparation.

  • HOLD - A restaurant employee paused the menu item selection so that it does not appear in the KDS for preparation.

  • SENT - The menu item selection was fired and appears in the KDS for preparation.

  • READY - Preparation is complete. The menu item selection is fulfilled and no longer appears in the KDS. If your restaurant does not use the Toast platform KDS, then order items do not reach the READY status.

Enum: "NEW" "HOLD" "SENT" "READY"
object (GiftCardSelectionInfo)

When a gift card is purchased, you can find the first five and last four digits of the gift card in this object if your API client has the orders.gift_cards:read scope. The last four digits are always shown. The first five digits are shown if:

  • The total number of digits in the gift card number is 15 or more.
  • The gift card provider does not encrypt the gift card.
  • The gift card is not entered by scanning a QR code.
guid
required
string

The GUID maintained by the Toast platform.

required
object (ConfigReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

object (ConfigReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

modifiedDate
string <date-time>

The date on which this selection was last modified. If not specified, defaults to the current time.

modifiers
Array of objects (Selection)

A list of modifiers that apply to this selection.

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 sets 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.

POST only. The openPriceAmount value is not present in orders API return data. It is used to populate receiptLinePrice.

object (ConfigReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

optionGroupPricingMode
string

Information about how the modifier group affects the pricing of its parent item.

Enum: "INCLUDED" "FIXED_PRICE" "ADJUSTS_PRICE" "REPLACES_PRICE" "LOCATION_SPECIFIC_PRICE"
preDiscountPrice
number <double>

Gross sale price for this selection. Excludes tax. Response only.

object (ConfigReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

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.

quantity
required
number <double>

Quantity ordered. For items sold by weight, a decimal number. For discrete items, a counting number.

receiptLinePrice
number <double>

The price of the menu item selection without any quantity, taxes, discounts, and modifier adjustments. If the menu item has taxes included, the receiptLinePrice value shows the original price, including taxes.

For example, if the menu item selection is for two orders of fries, receiptLinePrice is the price of one order of fries. If a menu item selection is for three large drinks, receiptLinePrice is the price of one large drink.

Populated based on the menu configuration, or using the value provided in externalPriceAmount or openPriceAmount.

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.

object (ConfigReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

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 shared by multiple guests.

  • -1 - Indicates that the restaurant employee did not select a seat for the menu item.

Response only.

selectionType
string

Specifies whether this selection is a special request or other off-menu sale.

If null or NONE, describes a normal modifier or item selection.

TOAST_CARD_SELL and TOAST_CARD_RELOAD are currently response-only.

Enum: "NONE" "OPEN_ITEM" "SPECIAL_REQUEST" "PORTION" "HOUSE_ACCOUNT_PAY_BALANCE" "TOAST_CARD_SELL" "TOAST_CARD_RELOAD"
object (ToastReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

tax
number <double>

The total tax amount for this selection. Response only.

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 that it applies to.

Valid values:

  • 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 is either INCLUDED or NOT_INCLUDED.
Enum: "INCLUDED" "NOT_INCLUDED" "INHERITED"
unitOfMeasure
string

The unit of measure required for weighing the item.

The default is NONE, which means that the item is not meant to be weighed.

Enum: "NONE" "LB" "OZ" "KG" "G"
voidBusinessDate
integer

The business date (yyyyMMdd) on which this selection was voided. Response only.

voidDate
string <date-time>

The date on which this selection was voided. Response only.

voided
boolean

Set to true if this selection is voided. Response only.

object (ExternalReference)

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

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. The requestId that is attached to this error can be referenced by the Toast support team.

post/orders/{orderGuid}/checks/{checkGuid}/selections
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "guid": "string",
  • "entityType": "string",
  • "externalId": "string",
  • "openedDate": "2025-02-07T08:00:00.000-0800",
  • "modifiedDate": "2025-02-07T08:00:00.000-0800",
  • "promisedDate": "2025-05-01T08:00:00.000-0800",
  • "diningOption": {
    },
  • "checks": [
    ],
  • "table": {
    },
  • "serviceArea": {
    },
  • "restaurantService": {
    },
  • "revenueCenter": {
    },
  • "source": "string",
  • "duration": 0,
  • "deliveryInfo": {
    },
  • "requiredPrepTime": "string",
  • "estimatedFulfillmentDate": "2025-05-01T08:00:00.000-0800",
  • "numberOfGuests": 0,
  • "voided": true,
  • "voidDate": "2025-02-07T08:00:00.000-0800",
  • "voidBusinessDate": 0,
  • "paidDate": "2025-02-07T08:00:00.000-0800",
  • "closedDate": "2025-02-07T08:00:00.000-0800",
  • "deletedDate": "2025-02-07T08:00:00.000-0800",
  • "deleted": true,
  • "businessDate": 0,
  • "server": {
    },
  • "pricingFeatures": [
    ],
  • "approvalStatus": "NEEDS_APPROVAL",
  • "guestOrderStatus": "string",
  • "createdDevice": {
    },
  • "createdDate": "2025-02-07T08:00:00.000-0800",
  • "initialDate": 0,
  • "lastModifiedDevice": {
    },
  • "curbsidePickupInfo": {
    },
  • "deliveryServiceInfo": {
    },
  • "marketplaceFacilitatorTaxInfo": {
    },
  • "createdInTestMode": true,
  • "appliedPackagingInfo": {
    },
  • "excessFood": true,
  • "displayNumber": "string"
}