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 update the following delivery information:

  • deliveryState: The current status of the delivery.

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

  • dispatchedDate: When the order was dispatched.

  • deliveredDate: When the order was delivered.

The delivery location values (for example, street address and city) and the delivery notes value 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.

    You can update any of the following values and only need to include the values you are updating.

    dispatchedDate

    The date and time when the restaurant indicated 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 the order was delivered.

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

    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.

    A typical order's deliveryState transitions from PENDING to PICKED_UP to IN_PROGRESS to DELIVERED. However, you might change the deliveryState to a previous value 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 assigned as the delivery driver.

    The delivery location values (for example, street address and city) and the delivery notes value 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.

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 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.

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 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 Delivery screen with the Unassigned tab emphasized.

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.

The Delivery screen with the Delivered tab emphasized.