This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

This section provides reference information about the endpoints and data types of the Toast orders API. For more information about using the orders API and code examples, see Orders. For general information about working with Toast APIs, see API overview.

Toast Orders API

Base URL: /orders/v2, Version: 2.2.0

The orders API includes operations that create, update, and retrieve information about restaurant guest orders.

Information on orders includes the checks, the items ordered, prices, payments, and discounts.

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.

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Tag: Orders

Operation Description
POST /prices

Get order prices

GET /orders/{guid}

Get an order

GET /ordersBulk

Get multiple orders

POST /orders/{orderGuid}/checks/{checkGuid}/selections

Add items to a check

PATCH /orders/{orderGuid}/deliveryInfo

Update delivery information

POST /orders

Post an order

GET /orders

Get order identifiers (deprecated)

Tag: Payments

Operation Description
GET /payments

Get payment identifiers

GET /payments/{guid}

Get a payment

POST /orders/{orderGuid}/checks/{checkGuid}/payments

Post payments

PATCH /orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid}

Update a tip amount

Tag: Discounts

Operation Description
POST /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts

Add check-level discounts

POST /orders/{orderGuid}/checks/{checkGuid}/selections/{selectionGuid}/appliedDiscounts

Add item-level discounts

POST /applicableDiscounts

Get applicable discounts

Paths

Get applicable discounts

POST /applicableDiscounts

Tags: Discounts

Returns an array of ApplicableDiscount objects that contain information about the discounts that apply to the checks and menu item selections in an order.

Each ApplicableDiscount object contains information that you can use to determine which items and checks are eligible for the discount.

If you include a promoCode value in the ApplicableDiscount object, the applicableDiscounts endpoint returns the only the discounts that are associated with that promotional code.

Uses default content-types: application/json

A JSON ApplicableDiscountsRequest object containing information about an order, and an optional promoCode.

Toast-Restaurant-External-ID

The identifier of the restaurant.

header string

application/json

200 OK

A JSON array of ApplicableDiscount objects.

400 Bad Request

Invalid arguments

500 Internal Server Error

An unexpected internal error occurred. The requestId that is attached to this error can be referenced by Toast.

Get order identifiers (deprecated)

GET /orders

Tags: Orders

Returns a list of the GUIDs of all orders opened during a period of time. You can return the list of orders for either a period of up to one hour or for one business day.

  • Specify both startDate and endDate to return the list of orders modified during a period of up to one hour.
  • Specify the businessDate to return the list of orders promised for delivery during a business day.
Toast-Restaurant-External-ID

The identifier for the restaurant to retrieve orders from.

header string
startDate

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

query string (ISO-8601)
endDate

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.

query string (ISO-8601)
businessDate

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.

query string

application/json

200 OK

A JSON array of the GUID identifiers for orders.

string
400 Bad Request

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 Internal Server Error

An unexpected internal error occurred. The requestId that is attached to this error can be referenced by Toast.

Post an order

POST /orders

Tags: Orders

Submits an order to the server. Returns a JSON Order object if successful.

Uses default content-types: application/json

A JSON object containing information about an order.

Toast-Restaurant-External-ID

The identifier for the restaurant where this order was placed.

header string

application/json

200 OK

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.

Example for application/json
{
"approvalStatus": "NEEDS_APPROVAL",
"businessDate": 20210730,
"checks": [
{
"amount": 5,
"appliedDiscounts": [
]
,
"appliedLoyaltyInfo": null,
"appliedServiceCharges": [
]
,
"closedDate": null,
"createdDate": "2021-07-30T11:57:46.282+0000",
"createdDevice": {
"id": null
}
,
"customer": {
"email": "severe@example.com",
"entityType": "Customer",
"firstName": "Severe",
"guid": "970e92e6-33b3-4caa-876b-2c6ef528ef4e",
"lastName": "Thibault",
"phone": "5555555555"
}
,
"deleted": false,
"deletedDate": null,
"displayNumber": "pdesjardins-api-1627646263",
"entityType": "Check",
"externalId": null,
"guid": "cbcb6fd5-d973-4e44-9b91-2abcee5ea6cd",
"lastModifiedDevice": {
"id": null
}
,
"modifiedDate": "2021-07-30T11:57:46.282+0000",
"openedDate": "2021-07-30T11:57:46.235+0000",
"paidDate": null,
"paymentStatus": "OPEN",
"payments": [
{
"amount": 8.5,
"amountTendered": null,
"cardEntryMode": null,
"cardType": null,
"cashDrawer": null,
"checkGuid": "cbcb6fd5-d973-4e44-9b91-2abcee5ea6cd",
"createdDevice": {
"id": null
}
,
"entityType": "OrderPayment",
"externalId": null,
"guid": "88642b2d-c359-4b96-bb8e-9cb3f5c2ac6a",
"houseAccount": null,
"last4Digits": null,
"lastModifiedDevice": {
"id": null
}
,
"mcaRepaymentAmount": null,
"orderGuid": "89488287-f259-435b-a654-0bc391596af0",
"originalProcessingFee": null,
"otherPayment": {
"entityType": "AlternatePaymentType",
"externalId": null,
"guid": "0dc19214-d29e-4ab9-a773-27e5812999c7"
}
,
"paidBusinessDate": 20210730,
"paidDate": "2021-07-30T11:57:46.237+0000",
"paymentStatus": "CAPTURED",
"refund": null,
"refundStatus": "NONE",
"server": null,
"tipAmount": 0,
"type": "OTHER",
"voidInfo": null
}
]
,
"selections": [
{
"appliedDiscounts": [
]
,
"appliedTaxes": [
]
,
"createdDate": "2021-07-30T11:57:46.269+0000",
"deferred": false,
"diningOption": {
"entityType": "DiningOption",
"externalId": null,
"guid": "18855a26-40d4-4a8f-b484-c6af211dd597"
}
,
"displayName": "蟹餅 CRAB CAKES",
"entityType": "MenuItemSelection",
"externalId": null,
"fulfillmentStatus": "NEW",
"guid": "2c8b6ece-c503-4f85-aed7-6a8c6526ba0d",
"item": {
"entityType": "MenuItem",
"externalId": null,
"guid": "9c59d4ab-8242-450f-8f36-b16e1b3ab802"
}
,
"itemGroup": {
"entityType": "MenuGroup",
"externalId": null,
"guid": "881472e6-dd94-48c6-b5c6-25e51a864208"
}
,
"modifiedDate": "2021-07-30T11:57:46.269+0000",
"modifiers": [
]
,
"optionGroup": null,
"optionGroupPricingMode": null,
"preDiscountPrice": 5,
"preModifier": null,
"price": 5,
"quantity": 1,
"receiptLinePrice": 5,
"refundDetails": null,
"salesCategory": {
"entityType": "SalesCategory",
"externalId": null,
"guid": "c0915e46-341e-4ec0-b46e-cb87fab729fd"
}
,
"seatNumber": -1,
"selectionType": "NONE",
"tax": 0,
"taxInclusion": "NOT_INCLUDED",
"unitOfMeasure": "NONE",
"voidBusinessDate": null,
"voidDate": null,
"voidReason": null,
"voided": false
}
]
,
"tabName": null,
"taxAmount": 0,
"taxExempt": false,
"totalAmount": 5,
"voidBusinessDate": null,
"voidDate": null,
"voided": false
}
]
,
"closedDate": null,
"createdDate": "2021-07-30T11:57:46.286+0000",
"createdDevice": {
"id": null
}
,
"curbsidePickupInfo": null,
"deleted": false,
"deletedDate": null,
"deliveryInfo": {
"address1": "401 Park Drive",
"address2": "Suite 801",
"city": "Boston",
"deliveredDate": null,
"deliveryEmployee": null,
"deliveryState": null,
"dispatchedDate": null,
"latitude": 42.3446671,
"longitude": -71.1023575,
"notes": "Please ring the doorbell.",
"state": "MA",
"zipCode": "02215"
}
,
"diningOption": {
"entityType": "DiningOption",
"externalId": null,
"guid": "18855a26-40d4-4a8f-b484-c6af211dd597"
}
,
"duration": null,
"entityType": "Order",
"estimatedFulfillmentDate": "2021-07-30T12:12:46.235+0000",
"externalId": null,
"guid": "89488287-f259-435b-a654-0bc391596af0",
"lastModifiedDevice": {
"id": null
}
,
"modifiedDate": "2021-07-30T11:57:46.286+0000",
"numberOfGuests": 1,
"openedDate": "2021-07-30T11:57:46.235+0000",
"paidDate": null,
"pricingFeatures": [
"TAXESV2"
]
,
"promisedDate": null,
"requiredPrepTime": "PT15M",
"restaurantService": null,
"revenueCenter": null,
"server": {
"entityType": "RestaurantUser",
"externalId": null,
"guid": "c89d1e72-1888-469f-a24b-506c66eafab7"
}
,
"serviceArea": null,
"source": "API",
"table": null,
"voidBusinessDate": null,
"voidDate": null,
"voided": false
}
400 Bad Request

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 Not Found

An entity referenced in the order does not exist, or belongs to a restaurant the authenticated client is not authorized to access.

413 Request Entity Too Large

The number of checks in the submitted order exceeds the limit.

415 Unsupported Media Type

The request did not have "application/json" in the Content-Type header.

500 Internal Server Error

An unexpected internal error occurred. There is a requestId attached to this error that can be referenced by Toast.

Get an order

GET /orders/{guid}

Tags: Orders

Retrieves detailed information about a single order, specified by its GUID.

Toast-Restaurant-External-ID

The identifier of the restaurant where this order was placed.

header string
guid

The GUID for the order to be returned.

path string

application/json

200 OK

A JSON Order object.

400 Bad Request

The GUID was malformed.

404 Not Found

The specified order was not found.

500 Internal Server Error

There was a problem serializing the order entity.

Add check-level discounts

POST /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts

Tags: Discounts

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.

Uses default content-types: application/json

A JSON array of Discount objects that identify the discounts you are adding.

orderGuid

The Toast platform identifier of the order that you are adding a discount to.

path string
checkGuid

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

path string

application/json

200 OK

A JSON Order object that includes the discount you added.

Post payments

POST /orders/{orderGuid}/checks/{checkGuid}/payments

Tags: Payments

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.

Uses default content-types: application/json

An array of JSON Payment objects containing information about the payments you are adding.

orderGuid

The Toast platform identifier of the order that you are adding payments to.

path string
checkGuid

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

path string

application/json

200 OK

A JSON Order object that includes the payments that you added.

Update a tip amount

PATCH /orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid}

Tags: Payments

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.

Uses default content-types: application/json

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.

orderGuid

The Toast platform identifier of the order that you are updating a tip in.

path string
checkGuid

The Toast platform identifier of the check that you are updating a tip in.

path string
paymentGuid

The Toast platform identifier of the payment that you are updating a tip in.

path string

application/json

200 OK

A JSON Order object that includes the tip amount that you updated.

Add items to a check

POST /orders/{orderGuid}/checks/{checkGuid}/selections

Tags: Orders

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.

Uses default content-types: application/json

An array of JSON Selection objects that identify the menu items you are adding.

Toast-Restaurant-External-ID

The identifier of the restaurant.

header string
orderGuid

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

path string
checkGuid

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

path string

application/json

200 OK

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 Bad Request

The request contains data that is not supported by the API.

404 Not Found

An entity referenced in the order does not exist at the restaurant.

500 Internal Server Error

An unexpected internal error occurred. The requestId that is attached to this error can be referenced by the Toast support team.

Add item-level discounts

POST /orders/{orderGuid}/checks/{checkGuid}/selections/{selectionGuid}/appliedDiscounts

Tags: Discounts

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.

Uses default content-types: application/json

A JSON array of Discount objects that identify the discounts you are adding.

orderGuid

The Toast platform identifier of the order that you are adding a discount to.

path string
checkGuid

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

path string
selectionGuid

The Toast platform identifier of the menu item selection that you are adding a discount to.

path string

application/json

200 OK

A JSON Order object that includes the discount you added.

Update delivery information

PATCH /orders/{orderGuid}/deliveryInfo

Tags: Orders

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, or a combination of the four.

Specify the Toast platform GUID of the order in the PATCH path parameters. Returns a JSON Order object if successful.

For more information, see the Toast Developer Guide.

Uses default content-types: application/json

A JSON deliveryInfo object containing the delivery information you want to update for an order.

You can update the deliveredDate, dispatchedDate, deliveryState, or DeliveryEmployee.

These are the only values you can update with this endpoint.

Toast-Restaurant-External-ID

The identifier of the restaurant.

header string
orderGuid

The Toast platform identifier of the order that you are updating the delivery information for.

path string

application/json

200 OK

Success. The response body contains the full order JSON, including information you updated in the deliveryInfo object.

400 Bad Request

The request contains data that is not supported by the API.

Get multiple orders

GET /ordersBulk

Tags: Orders

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.

Toast-Restaurant-External-ID

The identifier for the restaurant that processed the orders.

header string
startDate

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.

query string (ISO-8601)
endDate

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.

query string (ISO-8601)
businessDate

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.

query string
pageSize

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.

query integer
page

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.

query integer

application/json

200 OK

A JSON array of Order objects for each order processed during the period of time that you specify in your request.

400 Bad Request

The request contains data that is not supported by the API.

500 Internal Server Error

An unexpected internal error occurred. The requestId that is attached to this error can be referenced by the Toast support team.

Get payment identifiers

GET /payments

Tags: Payments

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.

Toast-Restaurant-External-ID

The GUID of the restaurant used as the context of the request.

header string
paidBusinessDate

Returns a list of the payments that were made during one business day.

Specify the business day in the format yyyyMMdd. For example, 20170101.

query string
refundBusinessDate

Returns a list of the payments that were refunded during one business day.

Specify the business day in the format yyyyMMdd. For example, 20170101.

query string
voidBusinessDate

Returns a list of the payments that were voided during one business day.

Specify the business day in the format yyyyMMdd. For example, 20170101.

query string

application/json

200 OK

A JSON array of the GUID identifiers for the payments.

string
Get a payment

GET /payments/{guid}

Tags: Payments

Returns a JSON Payment object containing detailed information about a single payment, specified by its GUID.

Toast-Restaurant-External-ID

The GUID of the restaurant used as the context of the request.

header string
guid

The GUID for the payment you want to return.

path string

application/json

200 OK

Returns a JSON Payment object.

400 Bad Request

The GUID was malformed.

404 Not Found

The specified payment was not found.

Get order prices

POST /prices

Tags: Orders

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.

Uses default content-types: application/json

A required JSON Order object containing information about the checks, item selections, modifier options, and other parts of the order.

Toast-Restaurant-External-ID

The identifier of the restaurant to be used for this price calculation.

header string

application/json

200 OK

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.

400 Bad Request

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 Forbidden

The API client does not have access to the restaurant, the API client does not have the orders:read scope, or both.

404 Not Found

An entity referenced in the order does not exist, or belongs to a restaurant that the API client is not authorized to access.

413 Request Entity Too Large

The number of checks in the submitted order exceeds the limit.

415 Unsupported Media Type

The request did not have application/json in the Content-Type HTTP header field.

500 Internal Server Error

An unexpected internal error occurred. The requestId that is attached to the error can be referenced by the Toast support team.

Schema definitions

ApplicableDiscount: object

A wrapper object that contains information about a discount that you can apply to an order, and which checks or menu item selections you can apply it to.

discount: ToastReference

A ToastReference object containing the identifiers of the discount. Response only.

applicableChecks: object[]

If the discount is applicable to a check, this value holds an array of ExternalReference objects containing the identifiers of the checks.

applicableSelections: object[]

If the discount is applicable to a menu item selection, this value holds an array of ExternalReference objects containing the identifiers of the menu items.

ApplicableDiscountsRequest: object

A wrapper object that contains an Order object and an optional promotional code.

You include an ApplicableDiscountsRequest object in the message body of a POST request to the applicableDiscounts endpoint.

order: Order

An Order object that contains information about the order that you want to get discounts for.

promoCode: string

An optional promotional code. If you include a promotional code, the applicableDiscounts endpoint returns only discounts that are associated with that promotional code.

AppliedDiscount:

A discount applied to a check or item. The Toast platform calculates service charges before it applies discounts. The system calculates tax after applying discounts.

In a POST request, you cannot apply open percent discounts. You can apply open amount discounts. You can only apply one discount to a menu item selection. For more information, see the Toast Developer Guide.

name: string

The name of the applied discount. Response only.

discountAmount: number (double)

The discount amount. This amount is subtracted from the check or item.

nonTaxDiscountAmount: number (double)

The amount that a discount reduces a menu item price, excluding any discount amount applied to taxes.

In most cases, a discount only applies to the menu item price, and the nonTaxDiscountAmount is the same as the discountAmount.

If you apply a discount to a menu item that includes tax in its price, the nonTaxDiscountAmount is less than discountAmount.

discount: ToastReference

A GUID reference to the discount configured for the restaurant.

triggers: object[]

Optional items that triggered this discount. Response only.

approver: ExternalReference

The user who approved the discount. Response only.

processingState: string , x ∈ { PENDING_APPLIED , APPLIED , PENDING_VOID , VOID }

Applies to loyalty program discounts only. Loyalty program reward discounts are validated and then applied, or redeemed, by the third-party loyalty program service provider depending on the state of the Toast platform order.

This value indicates the state of the discount in that validation and application process. Response only.

Valid values:

  • PENDING_APPLIED - The loyalty program service provider confirmed that the reward discount is valid for the order and customer. The reward is not yet redeemed, or applied to the customer's loyalty account.
  • APPLIED - The reward discount is redeemed. The reward is no longer available from the customer's loyalty program account.
  • PENDING_VOID - The reward discount was removed from the Toast platform order. The reward is not available from the customer's loyalty program account until the loyalty program service provider processes the void operation.
  • VOID - The reward discount was removed from the Toast platform order and the reward is available from the customer's loyalty program account again.
loyaltyDetails: LoyaltyDetails

Information about the customer loyalty program discount that is being applied to the check.

comboItems: object[]

A list of menu item selections that this combo discount applies to. Empty for non-combo discounts. Response only.

appliedPromoCode: string

The promo code that was applied for this discount.

For a POSTed order, the Toast platform cannot validate the promo code.

discountType: string , x ∈ { BOGO , PERCENT , FIXED , OPEN_PERCENT , OPEN_FIXED , FIXED_TOTAL }

The behavior of this discount.

Valid values:

  • BOGO - Buy One, Get One. The guest receives a discount based on purchasing a specific item or items.
  • PERCENT - The guest receives a specific percentage off of the price.
  • FIXED - The guest receives a fixed currency amount off of the price.
  • OPEN_PERCENT - The guest receives a percentage off of the price. The percentage is specified when the order is placed.
  • OPEN_FIXED - The guest receives a currency amount off of the price. The amount is specified when the order is placed.
  • FIXED_TOTAL - The guest pays a specified discounted price when they purchase specific items. Also referred to as a combo discount.
discountPercent: number (double)

The percent value (0-100) of the applied discount when the discountType is PERCENT or OPEN_PERCENT. For other discount types, this value is null.

AppliedDiscountTrigger: object

The Selection that triggered the application of this discount

selection: ExternalReference
quantity: number (double)

The amount of the selection used to trigger the applied discount.

AppliedLoyaltyInfo:

Information about the customer loyalty program account associated with a check.

loyaltyIdentifier: string

An identifier for the loyalty program account. For POST orders, this identifier is transmitted to the loyalty program service provider to associate the check with the loyalty account.

maskedLoyaltyIdentifier: string

A representation of the identifier of the loyalty program account that can be displayed securely. For example: ************1234. The Toast POS displays this string to restaurant employees and guests.

You can optionally include this value when you POST an order. It is available in response data when you GET the order.

If you do not provide a maskedLoyaltyIdentifier when you POST an order, this value is null in response data.

The Toast POS app displays a masked representation of the loyaltyIdentifier. All characters except the last four are hidden.

vendor: string , x ∈ { TOAST , PUNCHH , PUNCHH2 , PAYTRONIX , APPFRONT , INTEGRATION }

The specific loyalty program service provider that supports the loyalty account.

accrualFamilyGuid: string

Response only. An internal Toast platform identifier for loyalty program transactions.

This is not returned from the initial POST order request and is available at a later time.

accrualText: string

Response only. A description of the loyalty program transaction to print on the customer's receipt. For example, "Earned 27 points."

The maximum length of the description string is 255 characters.

This is not returned from the initial POST order request and is available at a later time.

AppliedPreauthInfo: object

For internal use only.

guid: string

For internal use only.

token: string

For internal use only.

oneTimeUse: boolean

For internal use only.

preAuthAmount: number (double)

For internal use only.

cardType: string , x ∈ { VISA , MASTERCARD , AMEX , DISCOVER , JCB , DINERS , CITI , MAESTRO , LASER , SOLO , INTERAC , UNKNOWN }

For internal use only.

readerType: string , x ∈ { ACS_ACR31 , BBPOS , BBPOS_MSR , IDTECH_SHUTTLE , INGENICO_ICM122 , MAGTEK_BULLET , MAGTEK_DYNAMAG , MAGTEK_EDYNAMO , MAGTEK_UDYNAMO }

For internal use only.

last4CardDigits: string

For internal use only.

cardHolderFirstName: string

For internal use only.

cardHolderLastName: string

For internal use only.

cardHolderhash4: string

For internal use only.

cardHolderhash6: string

For internal use only.

magStripeName: string

For internal use only.

cardHolderExpirationMonth: string

For internal use only.

cardHolderExpirationYear: string

For internal use only.

useCount: integer

For internal use only.

AppliedServiceCharge:

A service charge that is added to a check. A service charge can represent an upcharge such as a gratuity or a delivery fee.

Whether the upcharge is taxable is defined in the restaurant-configured serviceCharge.

The fields on the AppliedServiceCharge are calculated based on the referenced ServiceCharge configuration.

chargeAmount: number (double)

The final applied amount excluding tax. Required if chargeType is OPEN.

serviceCharge: ExternalReference

A reference to the restaurant-configured service charge. If a service charge is taxable, the tax amount is applied to the check.

chargeType: string , x ∈ { FIXED , PERCENT , OPEN }

The type of service charge. Response only.

Valid values:

  • FIXED - The service charge is for a specific currency amount.

  • PERCENT - The service charge is for a percentage of the check amount.

  • OPEN - The service charge is not configured with an amount. The amount is specified by the restaurant employee.

name: string

The configured human readable label for the service charge. Response only.

delivery: boolean

Whether this service charge is a delivery charge. Response only.

takeout: boolean

Whether this service charge is a takeout charge. Response only.

dineIn: boolean

Whether this service charge is a dine-in charge. Response only.

gratuity: boolean

Whether this service charge is a gratuity. Can be used to derive required tip amount on the check. Response only.

taxable: boolean

Whether this service charge is taxable. Response only.

appliedTaxes: object[]

Taxes applied to the service charge.

serviceChargeCalculation: string , x ∈ { PRE_DISCOUNT , POST_DISCOUNT }

Defines whether a PERCENT service charge is applied before (PRE_DISCOUNT) or after (POST_DISCOUNT) discounts.

This field is null for FIXED and OPEN service charges.

refundDetails: RefundDetails

A RefundDetails object that contains information about refunded payment amounts for the item.

AppliedTaxRate:

A tax rate that is applied to an item or service charge.

entityType: string

The type of object this is.

taxRate: ToastReference
name: string

The name of the tax rate.

rate: number (double)

The tax rate, which can be a fixed amount, a percentage, or null.

taxAmount: number (double)

The tax amount that was actually applied.

type: string , x ∈ { PERCENT , FIXED , NONE , TABLE , EXTERNAL }

The type of the tax rate. Default is PERCENT.

The value EXTERNAL indicates that the tax is for a marketplace facilitator order, and that the marketplace facilitator organization calculated the tax amount.

facilitatorCollectAndRemitTax: boolean

Indicates whether the marketplace facilitator that received a guest order remitted the tax amount on behalf of the Toast platform restaurant.

You can use this information to identify tax amounts that have already been paid by an ordering service provider and do not need to be paid again.

  • true - The marketplace facilitator paid the tax amount on behalf of the Toast platform restaurant location.

  • false - The marketplace facilitator has not paid the tax amount. The Toast platform restaurant location may be required to pay the tax amount.

Note: Toast API response data is not guidance or advice for tax compliance.

Check:

Represents a single check within an order.

createdDate: string (date-time)

The date and time that the Toast platform received the check.

openedDate: string (date-time)

The date on which this check was opened. If not specified, it is set to the current system time.

closedDate: string (date-time)

The most recent date on which this check's payment status was set to CLOSED.

modifiedDate: string (date-time)

The most recent date on which this check was modified.

deletedDate: string (date-time)

The date on which this check was deleted.

deletedDate is only applicable when deleted is true.

If deleted is false, then deletedDate is set to the UNIX epoch, 1970-01-01T00:00:00.000+0000.

deleted: boolean

Set to true if this check was deleted.

selections: object[]
customer: Customer

A Customer object that holds information about a restaurant guest that is associated with the check.

Required for POST requests for orders that use the takeout or delivery dining options.

For checks that apply or accrue Toast loyalty points, a GET request returns a Customer object even when restaurant employees do not enter guest information for a check. In this case, the Customer object contains only the Toast platform GUID of the guest. All other values are null.

appliedLoyaltyInfo: AppliedLoyaltyInfo

Information about the customer loyalty program account associated with the check. Used to accrue loyalty program benefits and to redeem loyalty program discounts.

taxExempt: boolean

Set to true if this check is tax exempt. The tax exempt number is not yet supported.

displayNumber: string

Generally starts at one each day and counts up. The Toast platform fills this in if it is not specified when the order is POSTed. Not guaranteed to be unique.

appliedServiceCharges: object[]

Any restaurant-configured service charges that applied to this check.

amount: number (double)

The total calculated price of this check after discounts. Does not include taxes. Response only.

netAmount: number (double)

For internal use only.

taxAmount: number (double)

The calculated tax amount. Includes service charge and item level taxes. Response only.

tipAmount: number (double)

For internal use only.

totalAmount: number (double)

The total calculated price of this check including discounts and taxes. Not affected by refunds. Response only.

totalDiscountAmount: number (double)

For internal use only.

payments: object[]

Payments made on this check.

tabName: string

The name of the tab on this check. This displays on the KDS (Kitchen Display System) for pending orders.

The tabName value can contain up to 255 characters.

paymentStatus: string , x ∈ { OPEN , PAID , CLOSED }

The payment status of this check.

Valid values:

  • OPEN - There is an outstanding balance.

  • PAID - A credit card payment was applied, but the tip has not been adjusted.

  • CLOSED - There is no remaining amount due on this check. For credit card payments, the payment has been adjusted to reflect the tip. Toast does not prevent a CLOSED check from transitioning back to OPEN or PAID.

Response only.

appliedDiscounts: object[]

The discounts applied to this check. In a POST request, only one appliedDiscount is allowed per check.

voided: boolean

True if this check is voided. Response only.

voidDate: string (date-time)

The date when this check was voided. Response only.

voidBusinessDate: integer

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

paidDate: string (date-time)

The most recent date when this check received payment. If not specified when POSTing, it is set to the current system time.

pickedUpDate: string (date-time)

For internal use only.

createdDevice: Device

The Toast POS device that created the check. This value is null if the check was not created using a Toast POS device.

lastModifiedDevice: Device

The Toast POS device that modified the check most recently. This value is null if the check was never modified using a Toast POS device.

If the check is modified but the modification was not made using a Toast POS device, then this value does not change.

appliedPreauthInfo: AppliedPreauthInfo

For internal use only.

shift: ExternalReference

For internal use only.

driverShift: ExternalReference

For internal use only.

ConfigReference:

A wrapper object containing identifier values for Toast platform entities.

multiLocationId: string

A consistent identifier for Toast platform entities, such as menu items, that applies to all versions of a shared entity at all locations in a restaurant group.

For example, you can use the multiLocationId value to identify menu entities that are versions of a shared menu entity. For more information about the menus API multilocationId value, see the Toast Developer Guide.

externalId: string

An external identifier that is prefixed by a naming authority. Deprecated for use in ConfigReference.

CurbsidePickupInfo:

Information that the restaurant can use to identify a guest when they arrive outside the restaurant to pick up their order. transportDescription is a required field.

transportColor: string (up to 20 chars)

The color of the guest's vehicle if they will arrive at the restaurant in a vehicle to pick up their order.

transportDescription: string (up to 100 chars)

Information about how the guest will arrive at the restaurant to pick up their order.

For example, the make and model of the vehicle the guest will arrive in.

notes: string (up to 100 chars)

Extra notes.

Customer:

firstName: string

The first name, or given name, of the guest.

lastName: string

The last name, or surname, of the guest.

phone: string

The telephone number of the guest.

phoneToken: string

For internal use only.

email: string

The email address corresponding to the guest who placed the order.

The email address is the key that identifies a unique restaurant guest. All distinct guests should have distinct email addresses.

emailToken: string

For internal use only.

DeliveryInfo: object

Information related to delivery orders. Required if the dining option behavior is DELIVERY.

address1: string

The first line of the street address of the delivery destination.

address2: string

The second line of the street address of the delivery destination.

city: string

The name of the city or town of the delivery destination.

state: string (ISO 3166-2)

The postal abbreviation of the state or province of the delivery destination.

The abbreviation must be in ISO 3166-2 format (two capital letters).

zipCode: string

The postal or zip code of the delivery destination.

latitude: number (double)

The north/south geographic coordinate of the delivery destination, in decimal format.

longitude: number (double)

The east/west geographic coordinate of the delivery destination, in decimal format.

notes: string

Additional instructions or information about the delivery.

deliveredDate: string (date-time)

The date and time that the delivery employee indicated in the Toast POS app that the order was delivered. Response only.

This value is only set when the dining option for the order is DELIVERY. For other dining options, the value is null.

dispatchedDate: string (date-time)

The date and time that the restaurant indicated in the Toast POS app that the order was available for delivery and assigned to a delivery employee.

This value is only set when the dining option for the order is DELIVERY. For other dining options, the value is null.

deliveryEmployee: ExternalReference

The Toast GUID of the employee who delivers the order.

deliveryState: string , x ∈ { PENDING , IN_PROGRESS , PICKED_UP , DELIVERED }

An internal representation of the state of a delivery order.

Valid values:

  • PENDING - The delivery is not dispatched. This corresponds to the Unassigned tab of the Delivery screen of the Toast POS app.

  • IN_PROGRESS - The order is on the way to the destination. This corresponds to the En Route tab of the Delivery screen of the Toast POS app.

  • PICKED_UP - The employee who delivers the order has picked up the order from the restaurant.

  • DELIVERED - The order was delivered. This corresponds to the Delivered tab of the Delivery screen of the Toast POS app.

DeliveryServiceInfo:

Reserved for future use.

providerId: string (up to 255 chars)

Reserved for future use.

providerName: string (up to 36 chars)

Reserved for future use.

driverName: string (up to 255 chars)

Reserved for future use.

driverPhoneNumber: string (up to 30 chars)

Reserved for future use.

providerInfo: string (byte)

Reserved for future use.

Device: object

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.

id: string

The physical id of the device

ExternalReference:

A wrapper object with fields that allow reference to a Toast platform entity by Toast GUID or a partner's identifier.

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.

GiftCardInfo:

Reserved for future use.

storedValueBalance: number (double)

Reserved for future use.

rewardsBalance: number (double)

Reserved for future use.

authRequestId: string

Reserved for future use.

authorizationState: string , x ∈ { VALIDATED , NONE , PAID , REVERSED , DENIED , ERROR , ADJUSTING }

Reserved for future use.

cardNumberIdentifier: string

Reserved for future use.

LoyaltyDetails: object

Information about the loyalty program discount that is applied to a check. The loyalty program account is identified in the AppliedLoyaltyInfo value for the check.

vendor: string , x ∈ { TOAST , PUNCHH , PUNCHH2 , PAYTRONIX , APPFRONT , INTEGRATION }

The specific loyalty program service provider that supports the loyalty account.

referenceId: string

The identifier of the loyalty program discount that is recognized by the loyalty program service provider.

The Toast platform transmits the discount identifier to the service provider to determine the validity and amount of the discount.

MarketplaceFacilitatorTaxInfo: object

Information about the taxes that a marketplace facilitator organization remits on behalf of a Toast platform restaurant. POST only. The orders API does not include the MarketplaceFacilitatorTaxInfo object in response 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.

facilitatorCollectAndRemitTaxOrder: boolean

Indicates whether a marketplace facilitator organization has paid the tax amounts for an order on behalf of the restaurant that fulfills the order.

If you include this value, you indicate that the marketplace facilitator order uses the prices and tax amounts calculated by the Toast platform.

If you include this value, you must not include the taxes value and you must not include the externalPriceAmount for menu item selections in the order.

taxes: object[]

An array of AppliedTaxRate objects that describe the tax amounts that apply to a marketplace facilitator order.

If you include this value, you must include an externalPriceAmount for each menu item selection in the order.

MoveItemRequest: object

Reserved for future use.

selectionIds: object

Reserved for future use.

number (double)
destCheckId: string

Reserved for future use.

Order:

A Toast platform order is composed of one or more checks. Each check has one or more menu item selections.

openedDate: string (date-time)

The business date of the order.

For dine-in and as soon as possible (ASAP) orders, openedDate should match createdDate.

For scheduled orders, openedDate should match promisedDate.

If you do not provide a value for openedDate value when you POST a new order, the business date of the order is set to the restaurant business day that corresponds to the current date and time.

The business date of an order is affected by the business date cutoff time for a restaurant, which is available from the restaurants API in the closeoutHour property.

modifiedDate: string (date-time)

The most recent date that the order, or a check or menu item selection in the order, was modified.

promisedDate: string (date-time)

For scheduled orders, the date and time that the order is scheduled to be fulfilled.

For dine-in and as soon as possible (ASAP) orders, promisedDate is null.

channelGuid: string (uuid)

The GUID representing the ordering channel that is attributed to the order. Examples of channels include Doordash and Toast Online Ordering.

diningOption: ExternalReference

The restaurant-configured dining option that applies to this order.

checks: object[]

The checks for this order. Most orders have one check.

If the check is split, then there are multiple checks.

table: ExternalReference

The restaurant table at which this order was placed.

serviceArea: ExternalReference

The service area. Response only.

restaurantService: ExternalReference

The applicable meal service. For example, lunch or dinner. Response only.

revenueCenter: ExternalReference

The division or section of a restaurant that the order is fulfilled in.

You use revenue centers to analyze financial reporting information.

source: string

Indicates the way that the order was placed.

Valid values:

  • In Store
  • Online
  • Order-and-Pay-at-Table
  • API
  • Kiosk
  • Caller Id
  • Google
  • Invoice
  • Toast Pickup App
  • Grubhub (deprecated)

Response only.

duration: integer

The number of seconds between creation and payment. Response only.

deliveryInfo: DeliveryInfo

Delivery information related to orders with a DELIVERY dining option.

requiredPrepTime: string (ISO-8601)

The amount of time that it will take to prepare the order. This value overrides the default deliveryPrepTime or takeoutPrepTime that normally controls auto-firing for scheduled orders.

You can use requiredPrepTime to handle atypical orders that will take more time than usual for a restaurant to prepare.

Express the required preparation time in ISO-8601 duration format. Must be greater than zero and be an increment of five minutes. For example, the value "PT15M" sets the required preparation time for the order to 15 minutes.

estimatedFulfillmentDate: string (date-time)

The date and time that the order is expected to be ready for pickup or to be delivered.

This value is only set when the order dining option uses the DELIVERY or TAKE_OUT dining behavior. For other dining options, the value is null.

Response only.

numberOfGuests: integer

The number of restaurant guests that are associated with the order. For example, for a dine-in order, this might be the number of guests at a table.

voided: boolean

Set to true if this order was voided. Response only.

voidDate: string (date-time)

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

voidBusinessDate: integer

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

paidDate: string (date-time)

The most recent date on which this order received payment. If not specified when POSTing, it is set to the current system time.

closedDate: string (date-time)

The most recent date on which the order payment status changed to CLOSED.

This status is not returned for the order. The order is simply CLOSED when all of the checks on the order are CLOSED.

deletedDate: string (date-time)

The date and time when the order was deleted.

The deletedDate value only applies when the deleted value is true.

If deleted is false, the value of deletedDate is the UNIX epoch, 1970-01-01T00:00:00.000+0000.

deleted: boolean

Set to true if this order is deleted. Response only.

For example, if you combine a check into another order, the original order for the check is deleted.

businessDate: integer

The business date (yyyyMMdd) on which the order was fulfilled. Response only.

server: ExternalReference

The restaurant employee, or server, who is assigned to the order.

owner: ExternalReference

For internal use only.

pricingFeatures: string[]

Pricing features that this order is using.

string , x ∈ { TAXESV2 , TAXESV3 }

A specific pricing feature used to price out the order.

approvalStatus: string , x ∈ { NEEDS_APPROVAL , APPROVED , FUTURE , NOT_APPROVED }

The current state of the order in the restaurant order fulfillment process. For example, the approvalStatus can indicate that an order is waiting for a restaurant employee to approve it or that the order is in a restaurant kitchen being fulfilled. Response only.

Valid values:

  • NEEDS_APPROVAL - The order is created but will not be fulfilled by the restaurant until an employee approves it.

  • APPROVED - The order is being fulfilled by the restaurant or it was fulfilled in the past. Orders remain in this state indefinitely after they are fulfilled.

  • FUTURE - The order is expected to be fulfilled by the restaurant at a future date and time. Restaurant employees will receive information about the order at the date and time that it is ready to be fulfilled.

  • NOT_APPROVED - Restaurant employees received information about the order but did not approve it for fulfillment. An order enters this state after a period of time passes without a restaurant employee approving it.

guestOrderStatus: string

Reserved for future use.

createdDevice: Device

The Toast POS device that created the order. This value is null if the order was not created using a Toast POS device.

createdDate: string (date-time)

The date and time that the Toast platform received the order.

initialDate: integer (int64)

Reserved for future use. Do not use the initialDate value for integration development.

lastModifiedDevice: Device

The Toast POS device that modified the order most recently. This value is null if the order was never modified using a Toast POS device.

If the order is modified but the modification was not made using a Toast POS device, this value does not change.

curbsidePickupInfo: CurbsidePickupInfo

Information that the restaurant can use to identify a guest when they arrive outside the restaurant to pick up their order.

deliveryServiceInfo: DeliveryServiceInfo

Reserved for future use.

marketplaceFacilitatorTaxInfo: MarketplaceFacilitatorTaxInfo

Information about the taxes that a marketplace facilitator organization remits on behalf of a Toast platform restaurant.

POST only. The orders API does not include the marketplaceFacilitatorTaxInfo value in response 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.

createdInTestMode: boolean

For internal use only.

OrderResponse: object

orders: object[]

Payment:

Defines a payment.

paidDate: string (date-time)

The date on which the payment was made.

paidBusinessDate: integer

The business date (yyyyMMdd) on which this payment was first applied. Response only.

type: string , x ∈ { CASH , CREDIT , GIFTCARD , HOUSE_ACCOUNT , REWARDCARD , LEVELUP , OTHER , UNDETERMINED }

The payment method.

When POSTing, only OTHER and CREDIT payment types are supported. For cash payments, you create an external cash payment type in Other Payment Options.

All other types are response only.

Valid values:

  • CASH - The guest paid in cash.
  • CREDIT - The guest used a credit card.
  • GIFTCARD - The guest used a gift card.
  • HOUSE_ACCOUNT - The guest used funds from their house account.
  • REWARDCARD - The guest used the available balance on a rewards card.
  • LEVELUP - The guest used the LevelUp app.
  • OTHER - The payment type is a custom type configured by the restaurant.
  • UNDETERMINED - The payment type cannot be determined.
cardEntryMode: string , x ∈ { SWIPED , KEYED , ONLINE , EMV_CHIP_SIGN , TOKENIZED , PRE_AUTHED , SAVED_CARD , FUTURE_ORDER , CONTACTLESS , APPLE_PAY_CNP , GOOGLE_PAY_CNP , INCREMENTAL_PRE_AUTHED , PARTNER_ECOM_COF }

Indicates how credit card data was obtained. Response only.

Valid values:

  • SWIPED - The credit card was swiped through a card reader.
  • KEYED - The restaurant employee typed the card number into a device.
  • ONLINE - The credit card information was entered online.
  • EMV_CHIP_SIGN - The credit card was inserted into a chip reader.
  • TOKENIZED - The credit card number is tokenized, meaning that it is replaced by a series of randomly generated numbers. The authorizer is able to use the token to authorize the actual credit card.
  • PRE_AUTHED - The credit card was pre-authorized for an initial amount. An example of pre-authorization is swiping a credit card to start a bar tab. The final payment is authorized when the order is complete.
  • SAVED_CARD - The credit card information was retrieved from the guest's account.
  • FUTURE_ORDER - The credit card payment was included on a scheduled order.
  • CONTACTLESS - The guest used a contactless payment option to provide the credit card number.
  • APPLE_PAY_CNP - The guest used the Apple Pay app to make the payment.
  • GOOGLE_PAY_CNP - The guest used the Google Pay app to make the payment.
  • INCREMENTAL_PRE_AUTHED - An additional payment was added to a pre-authorized card. For example, a guest uses a credit card to open a bar tab. As they continue to order more drinks, the pre-authorized amount is updated. The final payment is authorized when the order is complete.
  • PARTNER_ECOM_COF - The restaurant has the credit card on file.
amount: number (double)

The amount of this payment, excluding tips.

tipAmount: number (double)

The amount tipped on this payment.

amountTendered: number (double)

The amount tendered for this payment. The amount tendered does not include the tip.

cardType: string , x ∈ { VISA , MASTERCARD , AMEX , DISCOVER , JCB , DINERS , CIT , MAESTRO , LASER , SOLO , INTERAC , UNKNOWN }

The type of credit card that was used. Response only.

last4Digits: string

The last 4 digits of the credit card that was used. Response only.

originalProcessingFee: number (double)

The original processing fee for this payment. Populated after the payment is captured. Response only.

server: ExternalReference

The restaurant employee, or server, who is associated with the payment. Response only.

referenceCode: string

For internal use only.

cashDrawer: ExternalReference

A reference to the cashDrawer used to receive this payment. Response only.

refundStatus: string , x ∈ { NONE , PARTIAL , FULL }

Indicates whether the payment was refunded. Response only.

Valid values:

  • NONE - The payment was not refunded.
  • PARTIAL - The payment was partially refunded.
  • FULL - The payment was refunded in full.
refund: Refund

Response only.

paymentStatus: string , x ∈ { OPEN , PROCESSING , AUTHORIZED_AT_RISK , AUTHORIZED , ERROR , ERROR_NETWORK , DENIED , PROCESSING_VOID , VOIDED_AT_RISK , CANCELLED , CAPTURE_IN_PROGRESS , CAPTURED , VOIDED }

The status of this payment when the type is CREDIT. Response only.

Valid values:

  • OPEN - The payment has not been presented for processing.
  • PROCESSING - The payment is being processed.
  • AUTHORIZED_AT_RISK - This value is no longer used.
  • AUTHORIZED - The payment is approved but not yet captured. The card is valid and the funds are available.
  • ERROR - An error occurred during the payment processing.
  • ERROR_NETWORK - Unable to connect to the payment authorizer.
  • DENIED - The payment request was denied. For example, the provided credit card is over its limit.
  • PROCESSING_VOID - A void request for the payment is being processed.
  • VOIDED_AT_RISK - This value is no longer used.
  • CANCELLED - The payment is canceled.
  • CAPTURE_IN_PROGRESS - The payment is in the process of being captured.
  • CAPTURED - The payment is captured. When the payment is captured, the funds are transferred to the restaurant.
  • VOIDED - The payment is voided.
voidInfo: VoidInformation

If the payment was voided, this contains information about who did it and when. Response only.

houseAccount: ExternalReference

A reference to the house account, if any, that is associated with this payment. Response only.

otherPayment: ExternalReference

Required when the payment type is OTHER. A reference to an alternative payment method that was configured by the restaurant.

createdDevice: Device

The Toast POS device that created the payment. This value is null if the payment was not created using a Toast POS device.

lastModifiedDevice: Device

The Toast POS device that modified the payment most recently. This value is null if the payment was never modified using a Toast POS device.

If the payment is modified but the modification was not made using a Toast POS device, then this value does not change.

mcaRepaymentAmount: number (double)

The total currency amount withheld as repayment for a Toast Capital merchant cash advance (MCA). The MCA repayment amount is set at the time the payment is captured, which is typically hours after the actual restaurant guest payment.

Until the mcaRepaymentAmount is set, this value is null.

The mcaRepaymentAmount might be updated when the payment is settled, which is typically one or more days after the actual guest payment. Response only.

cardPaymentId: string

Note: this value is in limited release. Your orders API integration might not include the cardPaymentId value.

A unique identifier for the credit card used for a CREDIT type payment. The identifier string is generated by the Toast platform and does not include any information related to or associated with the actual credit card account. The identifier is unique within your restaurant management group.

The value is null for the following payment types:

  • Payment types other than CREDIT
  • Credit card payments entered using EMV (chip cards)
  • Credit card payments entered by keying in card numbers

Response only.

giftCard: ExternalReference

Reserved for future use.

giftCardInfo: GiftCardInfo

Reserved for future use.

orderGuid: string

The Toast platform identifier for the order that contains the payment. Response only.

checkGuid: string

The Toast platform identifier for the check that contains the payment. Response only.

receiptToken: string

For internal use only.

cardHolderFirstName: string

For internal use only.

cardHolderLastName: string

For internal use only.

isProcessedOffline: boolean

For internal use only.

processingService: string

For internal use only.

proRatedDiscountAmount: number (double)

For internal use only.

proRatedTaxAmount: number (double)

For internal use only.

proRatedTotalServiceChargeAmount: number (double)

For internal use only.

shift: ExternalReference

For internal use only.

serverShift: ExternalReference

For internal use only.

Refund: object

A currency amount removed from a guest payment.

refundAmount: number (double)

The amount of the refund, excluding the tip.

tipRefundAmount: number (double)

The amount of the tip refund.

refundDate: string (date-time)

The date and time when the refund was made.

refundBusinessDate: integer

The business date (yyyyMMdd) on which this refund was created. Response only.

refundTransaction: ToastReference

An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

refundStrategy: string , x ∈ { LEGACY_INCLUDE_REFUND_IN_AMOUNT_DUE , IGNORE_REFUND_IN_AMOUNT_DUE }

For internal use only.

RefundDetails: object

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.

refundAmount: number (double)

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

taxRefundAmount: number (double)

The tax amount being refunded.

refundTransaction: ToastReference

An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.

Selection:

A Selection object can represent either a primary item (for example, Check.selections) or a modifier (Selection.modifiers) selection. Quantity defaults to 1.

For a POST operation, all selections must have valid item and itemGroup fields. The item and itemGroup values can be null for GET requests. For example, they are null for gift cards and on special requests.

To specify a modifier selection, add it to the modifiers list of another selection. Each modifier selection must have its optionGroup field set correctly, because a MenuItem can be included in multiple MenuOptionGroups, potentially with different prices or sizing.

item: ConfigReference

A reference to the selected menu item.

itemGroup: ConfigReference

A reference to the menu group from which the item was selected.

optionGroup: ConfigReference

A reference to the modifier group from which the menu item was selected. Only applies if this is a modifier selection.

preModifier: ExternalReference

A reference to the selected pre-modifier.

quantity: number (double)

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

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.

unitOfMeasure: string , x ∈ { NONE , LB , OZ , KG , G }

The unit of measure required for weighing the item.

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

selectionType: string , x ∈ { NONE , OPEN_ITEM , SPECIAL_REQUEST , PORTION , HOUSE_ACCOUNT_PAY_BALANCE }

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

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

salesCategory: ExternalReference

A reference to the sales category of the item. Response only.

appliedDiscounts: object[]

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

deferred: boolean

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

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

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

voidDate: string (date-time)

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

voidBusinessDate: integer

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

voidReason: ExternalReference

If voided is true, a reference to the void reason. Response only.

refundDetails: RefundDetails

A RefundDetails object that contains information about refunded payment amounts for the item.

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.

createdDate: string (date-time)

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

modifiedDate: string (date-time)

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

modifiers: object[]

A list of modifiers that apply to this selection.

fulfillmentStatus: string , x ∈ { NEW (default) , HOLD , SENT , READY }

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.

taxInclusion: string , x ∈ { INCLUDED , NOT_INCLUDED , INHERITED }

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.
appliedTaxes: object[]

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

diningOption: ExternalReference

A reference to the setting or method that a restaurant uses to fulfill orders. For example, dine-in, takeout, or delivery might be dining options.

Restaurants configure the dining options that they fulfill orders in.

Response only.

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.

receiptLinePrice: number (double)

The price of the menu item selection before any quantity, taxes, discounts, and modifier option adjustments are applied.

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.

optionGroupPricingMode: string , x ∈ { INCLUDED , FIXED_PRICE , ADJUSTS_PRICE , REPLACES_PRICE , LOCATION_SPECIFIC_PRICE }

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

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.

toastGiftCard: ToastReference

For internal use only.

storedValueTransactionId: number (int64)

For internal use only.

SplitCheckRequest: object

Reserved for future use.

selectionIds: object

Reserved for future use.

number (double)

ToastReference: object

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

guid: string

The GUID maintained by the Toast platform.

entityType: string

The type of object this is. Response only.

UpdatePaymentRequest: object

A wrapper object containing payment fields that you can update. Currently you are only allowed to update a payment's tipAmount.

tipAmount: number (double)

The amount tipped on a payment.

VoidInformation: object

Information about a void applied to a check or item.

voidUser: ExternalReference

The user who voided the order.

voidApprover: ExternalReference

The user who approved the void.

voidDate: string (date-time)

The date on which the void was made.

voidBusinessDate: integer

The business date (yyyyMMdd) on which the void was made. Response only.

voidReason: ExternalReference

A reference to the configured void reason for the void.