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.

Creating delivery orders

A request for a delivery order must include the following:

  • The order's diningOption value must be set to a GUID that references a delivery dining option.

  • The order must have a customer value that contains information about the customer to whom the order will be delivered.

  • The order must have a deliveryInfo value that contains information about the address to which the order will be delivered.

The following example shows a JSON Order object that contains one check with a single menu item and a dining option set to delivery. Note that there is no payment information supplied with this order, but it can be included using the format shown in the dine-in order request.

Example POST request message body to create a delivery order

{
  "entityType": "Order",
  "diningOption": {
    "guid": "b1b10604-a8f9-4a21-ae86-7db974ee9dbf",1
    "entityType": "DiningOption"
  },
  "deliveryInfo": {2
    "address1": "401 Park Drive",
    "address2": "Suite 801",
    "city": "Boston",
    "state": "MA",
    "zipCode": "02215",
    "latitude": 42.3446671,
    "longitude": -71.1023575,
    "notes": ""
  },
  "checks": [
    {
      "entityType": "Check",
      "selections": [
        {
          "entityType": "MenuItemSelection",
          "itemGroup": {
            "guid": "75cd1156-c33a-4842-9cbd-717aebbf069e",
            "entityType": "MenuGroup"
          },
          "item": {
            "entityType": "MenuItem",
            "guid": "2478cec3-bca2-4956-a3aa-eda571d5518a"
          },
          "quantity": 1,
          "modifiers": []
        }
      ],
      "customer": {3
          "entityType": "Customer",
          "firstName": "Sarah",
          "lastName": "Gomez",
          "phone": "555-555-5555",
          "email": "sarah@example.com"4
      }
    }
  ]
}

1

The GUID of the dining option for the order. For this example, the dining option is delivery.

2

The deliveryInfo value contains information about the address to which the order will be delivered. This information is mandatory for delivery orders. The address1, city, state, and zipCode fields are required. Note that the state value must use the state abbreviation instead of the state full name (for example, "TX" instead of "Texas").

3

The customer value contains information about the customer to whom the order will be delivered. This customer information is mandatory for delivery orders. The firstName, lastName, phone, and email fields are required and the data must be correctly formatted.

4

The email value in a Customer object is the key value that indicates guest uniqueness. email must be unique per individual guest.


The following example shows the response data returned by the /orders endpoint of the orders API.

Example orders endpoint response data for a delivery order

{
  "guid": "4f0dbb70-46e8-4e02-bd22-9444cf9dc96b",1
  "entityType": "Order",
  "externalId": null,
  "revenueCenter": null,
  "server": null,
  "deliveryInfo": {2
    "address1": "401 Park Drive",
    "address2": "Suite 801",
    "city": "Boston",
    "state": "MA",
    "zipCode": "02215",
    "latitude": 42.3446671,
    "longitude": -71.1023575,
    "notes": "",
    "deliveredDate": null,3
    "dispatchedDate": null,4
    "deliveryEmployee": null5
  },
  "serviceArea": null,
  "numberOfGuests": 1,
  "diningOption": {
    "guid": "b1b10604-a8f9-4a21-ae86-7db974ee9dbf",
    "entityType": "DiningOption",
    "externalId": null
  },
  "source": "API",
  "voidDate": null,
  "openedDate": "2017-10-04T19:31:34.480+0000",6
  "duration": null,
  "businessDate": 20171004,
  "voidBusinessDate": null,
  "checks": [
    {
      "guid": "5a967d3f-b80a-41dc-8223-80665255dd9a",
      "entityType": "Check",
      "externalId": null,
      "displayNumber": "53",
      "amount": 9.99,
      "tabName": null,
      "taxExempt": false,
      "payments": [],
      "appliedDiscounts": [],
      "voidDate": null,
      "openedDate": "2017-10-04T19:31:34.482+0000",
      "totalAmount": 10.69,
      "selections": [
        {
          "guid": "25679951-23fa-4e29-a9e2-18b7f1c25cfb",
          "entityType": "MenuItemSelection",
          "externalId": null,
          "itemGroup": {
            "guid": "75cd1156-c33a-4842-9cbd-717aebbf069e",
            "entityType": "MenuGroup",
            "externalId": null
          },
          "deferred": false,
          "item": {
            "guid": "2478cec3-bca2-4956-a3aa-eda571d5518a",
            "entityType": "MenuItem",
            "externalId": null
          },
          "quantity": 1,
          "preDiscountPrice": 9.99,
          "voidReason": null,
          "optionGroup": null,
          "displayName": "Egg Sandwich",
          "appliedDiscounts": [],
          "tax": 0.7,
          "modifiers": [],
          "voidDate": null,
          "fulfillmentStatus": "NEW",7
          "salesCategory": null,
          "selectionType": "NONE",
          "voidBusinessDate": null,
          "createdDate": "2017-10-04T19:31:34.510+0000",
          "preModifier": null,
          "price": 9.99,
          "modifiedDate": "2017-10-04T19:31:34.510+0000",
          "voided": false,
          "appliedTaxes": [
            {
              "entityType": "AppliedTaxRate",
              "taxRate": {
                "guid": "92c6c470-74bb-4f84-b31f-2c144b70a285",
                "entityType": "TaxRate"
              },
              "name": "Local Tax",
              "rate": 0.0075,
              "taxAmount": 0.075,
              "type": "PERCENT"
            },
            {
              "entityType": "AppliedTaxRate",
              "taxRate": {
                "guid": "d5b88c05-1348-42ef-b1d3-577a83d70a80",
                "entityType": "TaxRate"
              },
              "name": "State Tax",
              "rate": 0.0625,
              "taxAmount": 0.625,
              "type": "PERCENT"
            }
          ]
        }
      ],
      "voidBusinessDate": null,
      "deleted": false,
      "paidDate": null,
      "closedDate": null,
      "deletedDate": null,
      "modifiedDate": "2017-10-04T19:31:34.547+0000",
      "appliedLoyaltyInfo": null,
      "voided": false,
      "taxAmount": 0.7,
      "appliedServiceCharges": [],8
      "paymentStatus": "OPEN",
      "customer": {9
        "guid": "479ad7e0-1942-42a5-874e-8cab3871190b",
        "entityType": "Customer",
        "firstName": "Sarah",
        "lastName": "Gomez",
        "phone": "5555555555",
        "email": "sarah@example.com"
      }
    }
  ],
  "deleted": false,
  "paidDate": null,
  "closedDate": null,
  "deletedDate": null,
  "restaurantService": null,
  "modifiedDate": "2017-10-04T19:31:34.549+0000",
  "promisedDate": null,
  "voided": false,
  "estimatedFulfillmentDate": "2017-10-04T20:31:34.480+0000",10
  "table": null
}

1

The unique identifier that the Toast platform assigns to the order.

2

Information about the address to which the order will be delivered.

3

The date and time that the delivery employee indicated that the order is delivered. The value is null because the order has not yet been delivered.

4

The date and time that the restaurant indicated that the order was available for delivery and assigned to a delivery employee. The value is null because the order is not yet available for delivery.

5

The Toast GUID or external identifier of the delivery employee. The value is null because a delivery employee has not been assigned to this order.

6

The date and time that the order was created.

7

A status indicating where the selection currently is in the preparation workflow. A status of "NEW" means the menu item selection has been added to a check but has not been sent to the KDS (Kitchen Display System) for preparation.

8

Any restaurant-configured service charges that applied to this check, such as a gratuity or a delivery fee. For information on service charges, see Service charges for checks.

9

Information about the customer to whom the order will be delivered.

10

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