Updating delivery information for an order

Important

To use this functionality, you must be granted access by Toast.

You can use the orders API to update the delivery information for a delivery order, including:

  • The current status of the delivery

  • The employee who makes the delivery (requires additional permissions)

  • When the order was dispatched

  • When the order was delivered

You cannot update the delivery address fields or the delivery notes.

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.

To update the delivery information for an existing order

  1. Find the Toast platform GUID for the order that you are updating the delivery information for. The order dining option must have behavior set to DELIVERY. For information about order dining options, see Order details based on the order dining option.

    • If your integration submits orders to Toast, then the response from the POST request to create an order contains the order GUID.

    • You can send a GET request to get the details for orders that were updated during a specific time interval. See Getting detailed information about multiple orders. The order details include the order GUID.

  2. If you plan to update the deliveryEmployee, find the Toast platform GUID of the employee to assign as the delivery driver.

    Note that to be able to update the delivery employee on an order, you must obtain additional permission from Toast. To retrieve employee GUIDs, you must have the labor.employees:read scope.

    For information on retrieving employee details, see Getting all employees of a restaurant.

  3. Create a JSON DeliveryInfo object that contains the delivery information that you want to update.

    You can update any of the following values. You only need to provide the values that you are updating.

    dispatchedDate

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

    For more information on formatting dates and times, see Dates and timestamps.

    deliveredDate

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

    For more information on formatting dates and times, see Dates and timestamps.

    deliveryState

    The state of the order delivery. 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.

    In a normal flow, deliveryState goes from PENDING to PICKED_UP to IN_PROGRESS to DELIVERED. However, you might change the deliveryState to a previous value in order to correct an error. For example, the delivery employee marks the wrong order as DELIVERED and needs to revert it to IN_PROGRESS.

    deliveryEmployee

    Contains the Toast platform GUID of the employee that is assigned as the delivery driver.

    To be able to update deliveryEmployee, you must obtain additional permission from Toast.

    You cannot update the delivery address fields or the delivery notes.

    For an example, see Example DeliveryInfo object.

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

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

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

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

    The response contains the full Order object. For an example, see Example response when updating delivery information.

Example DeliveryInfo object

The following example shows the DeliveryInfo object for updating delivery information for an order. 

{
  "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
  }
}

1

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

2

The date and time that the restaurant indicated that 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.

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": "",
    "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 that is assigned to this order.

2

Information about the delivery, including address information and any values that 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.