Updating delivery information for an order

Important

To use the /deliveryInfo endpoint, you'll need access to the orders.delivery_info:write scope. For more information about API client scopes, and how to get access to them, see Scopes.

You can use the orders API to modify the following delivery information:

Value	Description
deliveredDate	The date and time when the delivery employee indicated the order was delivered.
dispatchedDate	The date and time when the delivery employee indicated the order was delivered.
deliveryState	The status of the delivery order. The available values for deliveryState are: PENDING: The delivery order is not dispatched. Corresponds to the Unassigned tab for deliveries on the Toast POS application. PICKED_UP: The delivery employee has picked up the order from the restaurant. IN_PROGRESS: The order is on its way to the destination. Corresponds to the En Route tab for deliveries on the Toast POS application. DELIVERED: The order was delivered. Corresponds to the Delivered tab for deliveries on the Toast POS application.
deliveryEmployee	Contains the Toast platform GUID of the employee assigned as the delivery driver.
notes	The delivery notes for the order. When you update the order's delivery notes, any existing notes are overwritten.

Note

The delivery location values (for example, street address and city) cannot be updated.

How to update the delivery information

To update delivery information, you send a PATCH request to the /orders/{orderGuid}/deliveryInfo endpoint of the orders API. The request must include a JSON DeliveryInfo object that provides the updated values.

For more information about the endpoint used in this process, see the /deliveryInfo reference guide.

To update the delivery information for an existing order

1. Locate the Toast platform GUID for the order you are updating. For more information on locating an order GUID see Finding an order or check GUID.

2. If you plan to update an order's deliveryEmployee field, locate the Toast platform GUID of the employee to assign as the delivery driver. For information on retrieving employee details, see Getting all employees of a restaurant.

3. Create a JSON DeliveryInfo object that contains the delivery information you want to update. For the list of values you can modify see Delivery values.

   The delivery location values (for example, street address and city) cannot be updated.

   For an example DeliveryInfo object, see Example DeliveryInfo object.

4. Send a PATCH request to the /orders/{orderGuid}/deliveryInfo endpoint of the orders API.

   In the PATCH path, include the Toast platform GUID of the order.

   In the body of the request, include the DeliveryInfo object with the delivery information you want to update.

5. Examine the response data you receive from the orders API. Verify your request is processed successfully with a 200 HTTP code response.

   The response contains the full Order object. For an example, see this response.

Note

Once an order's deliveryState is DELIVERED, updates are no longer allowed.

Example DeliveryInfo object

The following example shows the DeliveryInfo object for updating delivery information for an order. For definitions of the values below, see Delivery values.

{
  "deliveredDate": "2021-09-14T17:57:42.263+0000",(1)
  "dispatchedDate": "2021-09-14T17:57:42.263+0000",(2)
  "deliveryState": "DELIVERED",(3)
  "deliveryEmployee": {
    "guid": "e10f2ae0-9690-4ab2-86fe-fa6603d708d0"(4)
  },
    "notes": "Leave order at door."(5)
}

• (1):

  The date and time when the delivery employee indicated the order was delivered.

• (2):

  The date and time the restaurant indicated the order was available for delivery and was assigned to a delivery employee.

• (3):

  The state of a delivery order. The possible values are PENDING, IN_PROGRESS, PICKED_UP, or DELIVERED.

• (4):

  The Toast platform GUID of the delivery employee at the restaurant.

• (5):

  The delivery notes for the order.

Example response when updating delivery information

The following example shows the response for a PATCH request to the /orders/{orderGuid}/deliveryInfo endpoint of the orders API.

{
  "guid": "d16ceaeb-d8a3-4d47-82db-0199d37c0713",(1)
  "entityType": "Order",
 
 [contents omitted]

  "deliveryInfo": {(2)
    "address1": "401 Park Drive",
    "address2": "Suite 801",
    "city": "Boston",
    "state": "MA",
    "zipCode": "02215",
    "latitude": 42.3446671,
    "longitude": -71.1023575,
    "notes": "Leave order at door.",
    "deliveredDate": "2021-09-14T17:57:42.263+0000",
    "dispatchedDate": "2021-09-14T17:57:42.263+0000",
    "deliveryEmployee": {
      "guid": "e10f2ae0-9690-4ab2-86fe-fa6603d708d0",
      "entityType": "RestaurantUser",
      "externalId": null
    },
    "deliveryState": "DELIVERED"
  },

  [contents omitted]

  "diningOption": {
    "guid": "f6cd5b58-27d7-462a-922f-7f919a6f9137",(3)
    "entityType": "DiningOption",
    "externalId": null
  },
 
  [contents omitted]

}

• (1):

  The Toast platform GUID assigned to this order.

• (2):

  Information about the delivery, including address information and any values you updated.

• (3):

  The Toast platform GUID of the dining option for this order. For delivery orders, the dining option must have behavior set to DELIVERY.

Viewing the delivery information in the Toast POS application

The following image shows an order on the Unassigned tab of the Delivery screen on a Toast POS device.

The following image shows the order on the Delivered tab after a PATCH request changed the order status to DELIVERED and added a delivery employee.