Post an order

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

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.

guid
required
string

The GUID maintained by Toast. Response only.

entityType
required
string

The type of object this is. Response only.

externalId
string

External identifier string that is prefixed by the naming authority. You can use the orders API to set an externalId for an order and then GET the order with that externalId.

openedDate
string <date-time>

The business date of the order. If you do not include an 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 one of the nested entities (check/selection) was modified.

promisedDate
string <date-time>

The date this order needs to be fulfilled by. Set to null for ASAP orders.

required
object (schemas)

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

required
Array of objects (schemas) non-empty

Checks for this order. Usually there will be one. If splitting the check, there will be multiple.

object (schemas)

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

object (schemas)

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

object (schemas)

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

object (schemas)

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

source
string

Indicates the way that the order was placed. One of:

  • In Store
  • Online
  • OPT
  • API
  • Kiosk
  • Caller Id
  • Google
  • Invoice

Response only.

duration
integer

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

object (DeliveryInfo)

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

requiredPrepTime
string <ISO-8601>

Sets the amount of time that it will take to prepare the order. The value that you set overrides the default deliveryPrepTime or takeoutPrepTime that normally control auto-firing for future 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 dining option for the order is DELIVERY or TAKE_OUT. For other dining options, the value is null. Response only.

numberOfGuests
integer

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

voided
boolean

True if this order has been voided. Response only.

voidDate
string <date-time>

The date at 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 at which this order received payment. If not specified when POSTing, it will be set to the current system time.

closedDate
string <date-time>

The most recent date at which this order's payment status was set to CLOSED. This status is not returned, because it is simply CLOSED when all checks on the order are CLOSED.

deletedDate
string <date-time>

The date and time that 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 has been 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 is fulfilled. Response only.

object (schemas)

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

pricingFeatures
Array of strings

Pricing Features which are being used by this order

Items Enum: "TAXESV2" "TAXESV3"
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. The approvalStatus value can be:

  • NEEDS_APPROVAL - the order has been 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 has been 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 and 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"
guestOrderStatus
string

Reserved for future use.

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, do the following. From the overflow menu (⋮) select Device Status and then select the Device tab.

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.

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, do the following. From the overflow menu (⋮) select Device Status and then select the Device tab.

object (schemas)

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.

object (schemas)

Reserved for future use.

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.

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",
  • "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": {
    },
  • "pricingFeatures": [
    ],
  • "approvalStatus": "NEEDS_APPROVAL",
  • "guestOrderStatus": "string",
  • "createdDevice": {
    },
  • "createdDate": "2019-08-24T14:15:22Z",
  • "initialDate": 0,
  • "lastModifiedDevice": {
    },
  • "curbsidePickupInfo": {
    },
  • "deliveryServiceInfo": {
    },
  • "marketplaceFacilitatorTaxInfo": {
    }
}
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": [
    ]
}