Get order prices

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.

Securityoauth2
Request
header Parameters
Toast-Restaurant-External-ID
required
string

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

Request Body schema: application/json

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

object (AppliedPackagingInfo)

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

approvalStatus
string

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.

Enum: "NEEDS_APPROVAL" "APPROVED" "FUTURE" "NOT_APPROVED"
businessDate
integer

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

captureSequenceKey
integer

For internal use only

channelGuid
string <uuid>

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

required
Array of objects (Check) non-empty

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

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

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.

createdDate
string <date-time>

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

object (Device)

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.

createdInTestMode
boolean

Indicates whether the order was created while the restaurant was in test mode.

For more information, see this Toast Central article

object (CurbsidePickupInfo)

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

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.

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.

object (DeliveryInfo)

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

object (DeliveryServiceInfo)

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

required
object (ExternalReference)

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

duration
integer

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

entityType
required
string

The type of object this is. Response only.

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.

excessFood
boolean

Indicates whether the order was created to track excess food (for example, food waste) rather than a standard guest order. Response only.

For more information on the differences between guest orders and excess food orders, see Daily order for tracking excess food.

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.

guestOrderStatus
string

Reserved for future use.

guid
required
string

The GUID maintained by the Toast platform.

initialDate
integer <int64>

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

object (Device)

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.

object (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 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.

modifiedDate
string <date-time>

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

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.

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.

object (ExternalReference)

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

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.

pricingFeatures
Array of strings

Pricing features that this order is using.

Items Enum: "TAXESV2" "TAXESV3"
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.

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.

object (ExternalReference)

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

object (ExternalReference)

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

object (ExternalReference)

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

object (ExternalReference)

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

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
  • Toast Local
  • Branded Online Ordering
  • Catering
  • Catering Online Ordering
  • Toast Tables
  • Grubhub (deprecated)

Response only.

object (ExternalReference)

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

voidBusinessDate
integer

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

voidDate
string <date-time>

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

voided
boolean

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

voidServiceCharges
boolean
Default: false

For internal use only

Responses
200

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

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

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

404

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

413

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

415

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

500

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

post/prices
Request samples
application/json
{
  • "guid": "string",
  • "entityType": "string",
  • "externalId": "string",
  • "openedDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z",
  • "promisedDate": "2019-08-24T14:15:22Z",
  • "channelGuid": "3c66b5cf-1850-49e6-aef3-40576e6de979",
  • "diningOption": {
    },
  • "checks": [
    ],
  • "table": {
    },
  • "serviceArea": {
    },
  • "restaurantService": {
    },
  • "revenueCenter": {
    },
  • "source": "string",
  • "duration": 0,
  • "deliveryInfo": {
    },
  • "requiredPrepTime": "string",
  • "estimatedFulfillmentDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "voided": true,
  • "voidDate": "2019-08-24T14:15:22Z",
  • "voidBusinessDate": 0,
  • "paidDate": "2019-08-24T14:15:22Z",
  • "closedDate": "2019-08-24T14:15:22Z",
  • "deletedDate": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "businessDate": 0,
  • "server": {
    },
  • "owner": {
    },
  • "pricingFeatures": [
    ],
  • "approvalStatus": "NEEDS_APPROVAL",
  • "guestOrderStatus": "string",
  • "createdDevice": {
    },
  • "createdDate": "2019-08-24T14:15:22Z",
  • "initialDate": 0,
  • "lastModifiedDevice": {
    },
  • "curbsidePickupInfo": {
    },
  • "deliveryServiceInfo": {
    },
  • "marketplaceFacilitatorTaxInfo": {
    },
  • "createdInTestMode": true,
  • "appliedPackagingInfo": {
    },
  • "captureSequenceKey": 0,
  • "excessFood": true,
  • "voidServiceCharges": false
}
Response samples
application/json
{
  • "guid": "string",
  • "entityType": "string",
  • "externalId": "string",
  • "openedDate": "2019-08-24T14:15:22Z",
  • "modifiedDate": "2019-08-24T14:15:22Z",
  • "promisedDate": "2019-08-24T14:15:22Z",
  • "channelGuid": "3c66b5cf-1850-49e6-aef3-40576e6de979",
  • "diningOption": {
    },
  • "checks": [
    ],
  • "table": {
    },
  • "serviceArea": {
    },
  • "restaurantService": {
    },
  • "revenueCenter": {
    },
  • "source": "string",
  • "duration": 0,
  • "deliveryInfo": {
    },
  • "requiredPrepTime": "string",
  • "estimatedFulfillmentDate": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 0,
  • "voided": true,
  • "voidDate": "2019-08-24T14:15:22Z",
  • "voidBusinessDate": 0,
  • "paidDate": "2019-08-24T14:15:22Z",
  • "closedDate": "2019-08-24T14:15:22Z",
  • "deletedDate": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "businessDate": 0,
  • "server": {
    },
  • "owner": {
    },
  • "pricingFeatures": [
    ],
  • "approvalStatus": "NEEDS_APPROVAL",
  • "guestOrderStatus": "string",
  • "createdDevice": {
    },
  • "createdDate": "2019-08-24T14:15:22Z",
  • "initialDate": 0,
  • "lastModifiedDevice": {
    },
  • "curbsidePickupInfo": {
    },
  • "deliveryServiceInfo": {
    },
  • "marketplaceFacilitatorTaxInfo": {
    },
  • "createdInTestMode": true,
  • "appliedPackagingInfo": {
    },
  • "captureSequenceKey": 0,
  • "excessFood": true,
  • "voidServiceCharges": false
}