Post an order

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

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

The identifier for the restaurant where this order was placed.

Request Body schema: application/json

A JSON object containing information about an 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

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.

400

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

An entity referenced in the order does not exist, or belongs to a restaurant the authenticated 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 header.

500

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

post/orders
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": "89488287-f259-435b-a654-0bc391596af0",
  • "entityType": "Order",
  • "externalId": null,
  • "revenueCenter": null,
  • "server": {
    },
  • "lastModifiedDevice": {
    },
  • "source": "API",
  • "voidDate": null,
  • "duration": null,
  • "businessDate": 20210730,
  • "paidDate": null,
  • "restaurantService": null,
  • "voided": false,
  • "estimatedFulfillmentDate": "2021-07-30T12:12:46.235+0000",
  • "table": null,
  • "requiredPrepTime": "PT15M",
  • "approvalStatus": "NEEDS_APPROVAL",
  • "deliveryInfo": {
    },
  • "serviceArea": null,
  • "curbsidePickupInfo": null,
  • "numberOfGuests": 1,
  • "diningOption": {
    },
  • "openedDate": "2021-07-30T11:57:46.235+0000",
  • "voidBusinessDate": null,
  • "checks": [
    ],
  • "deleted": false,
  • "createdDevice": {
    },
  • "createdDate": "2021-07-30T11:57:46.286+0000",
  • "closedDate": null,
  • "deletedDate": null,
  • "modifiedDate": "2021-07-30T11:57:46.286+0000",
  • "promisedDate": null,
  • "pricingFeatures": [
    ]
}