DeliveryStatusUpdate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/grubhub/main/json-schema/grubhub-deliverystatusupdate-schema.json",
  "title": "DeliveryStatusUpdate",
  "x-generated": "2026-09-17",
  "x-method": "derived",
  "x-source": "openapi/grubhub-connect-webhooks-openapi.yml#/components/schemas/DeliveryStatusUpdate",
  "type": "object",
  "description": "Provides information about the status of a delivery and the courier assigned to it, pushed to clients via webhook.",
  "properties": {
    "update_type": {
      "type": "string",
      "description": "The type of a DeliveryStatusUpdate.",
      "enum": [
        "DELIVERY_STATUS_UPDATE",
        "COURIER_LOCATION_UPDATE",
        "ETA_UPDATE"
      ]
    },
    "delivery": {
      "$ref": "#/$defs/Delivery"
    },
    "courier": {
      "$ref": "#/$defs/Courier"
    },
    "tracking_url": {
      "type": "string",
      "description": "The url for the delivery tracking UI."
    }
  },
  "required": [
    "delivery",
    "update_type"
  ],
  "$defs": {
    "Assigned": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the delivery has been assigned.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "Canceled": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        },
        {
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "description": "Types of actors who may update a delivery.",
              "enum": [
                "CLIENT",
                "GRUBHUB"
              ],
              "example": "CLIENT"
            },
            "reason_code": {
              "type": "string",
              "description": "Codes for reasons why a delivery was canceled.",
              "enum": [
                "MERCHANT_NOT_READY_FOR_PICKUP",
                "MERCHANT_UNABLE_TO_FULFILL_ORDER",
                "MERCHANT_CLOSED",
                "MERCHANT_PICKUP_DELAYED",
                "MERCHANT_ITEM_MISSING",
                "CUSTOMER_CONTENTS_ISSUE",
                "ORDER_PICKED_UP_BY_ANOTHER_DRIVER",
                "DRIVER_UNABLE_TO_FINISH_DELIVERY",
                "UNABLE_TO_ASSIGN_DRIVER",
                "DELIVERY_CANCELLATION_OTHER_REASON"
              ],
              "example": "CUSTOMER_CANCEL"
            },
            "reason_comment": {
              "type": "string",
              "description": "Additional detail about the cancellation.",
              "example": "Customer no longer wants delivery."
            }
          }
        }
      ],
      "description": "An event indicating that the delivery was canceled.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "ClientData": {
      "description": "Partner/client-supplied reference identifiers for this delivery.",
      "properties": {
        "external_id": {
          "type": "string",
          "description": "The partner's own identifier for this delivery."
        },
        "external_merchant_id": {
          "type": "string",
          "description": "The partner's identifier for the merchant associated with this delivery."
        },
        "external_source": {
          "type": "string",
          "description": "The source system that supplied the external identifiers."
        },
        "reference_number": {
          "type": "string",
          "description": "A partner-supplied reference number for this delivery."
        }
      }
    },
    "Courier": {
      "description": "A courier.",
      "properties": {
        "name": {
          "type": "string",
          "description": "The display name of the courier assigned to a delivery.",
          "example": "Nick"
        },
        "delivery_method": {
          "type": "string",
          "description": "Means of transportation by which a courier may be delivering.",
          "enum": [
            "CAR",
            "BIKE",
            "SCOOTER",
            "WALK"
          ],
          "example": "CAR"
        },
        "location": {
          "$ref": "#/$defs/GeoLocation"
        }
      },
      "required": [
        "delivery_method",
        "location",
        "name"
      ]
    },
    "CourierAtDropoff": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the assigned courier has arrived at the delivery's dropoff location.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "CourierAtPickup": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the assigned courier has arrived at the delivery's pickup location.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "Created": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event representing the creation of a delivery.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "Delivered": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        },
        {
          "type": "object",
          "properties": {
            "dropoff_image_details": {
              "allOf": [
                {
                  "$ref": "#/$defs/DropoffImageDetails"
                }
              ],
              "deprecated": true,
              "description": "Use `dropoff_image_details` in the `ProofOfDelivery` event instead."
            }
          }
        }
      ],
      "description": "An event indicating the delivery has been successfully delivered.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "Delivery": {
      "description": "The information and historical events associated with a delivery.",
      "properties": {
        "delivery_id": {
          "type": "string",
          "format": "uuid",
          "description": "A unique identifier of this delivery.",
          "example": "0ec346bd-635a-4a07-8f35-44962a8bcc5b"
        },
        "events": {
          "type": "array",
          "description": "A history of notable events that have occurred for this delivery.",
          "items": {
            "$ref": "#/$defs/DeliveryEvent"
          }
        },
        "estimated_event_times": {
          "$ref": "#/$defs/EstimatedEventTimes"
        },
        "client_data": {
          "$ref": "#/$defs/ClientData"
        }
      },
      "required": [
        "delivery_id",
        "estimated_event_times",
        "events"
      ]
    },
    "DeliveryEvent": {
      "description": "An event during the course of a single delivery's lifecycle.",
      "discriminator": {
        "propertyName": "type"
      },
      "oneOf": [
        {
          "$ref": "#/$defs/Created"
        },
        {
          "$ref": "#/$defs/Assigned"
        },
        {
          "$ref": "#/$defs/Unassigned"
        },
        {
          "$ref": "#/$defs/CourierAtPickup"
        },
        {
          "$ref": "#/$defs/PickupVerification"
        },
        {
          "$ref": "#/$defs/PickedUp"
        },
        {
          "$ref": "#/$defs/InTransit"
        },
        {
          "$ref": "#/$defs/CourierAtDropoff"
        },
        {
          "$ref": "#/$defs/Delivered"
        },
        {
          "$ref": "#/$defs/ProofOfDelivery"
        },
        {
          "$ref": "#/$defs/ReturnInitiated"
        },
        {
          "$ref": "#/$defs/ReturnCompleted"
        },
        {
          "$ref": "#/$defs/Canceled"
        }
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of this event.",
          "enum": [
            "CREATED",
            "ASSIGNED",
            "UNASSIGNED",
            "COURIER_AT_PICKUP",
            "PICKED_UP",
            "IN_TRANSIT",
            "COURIER_AT_DROPOFF",
            "DELIVERED",
            "PROOF_OF_DELIVERY",
            "RETURN_INITIATED",
            "RETURN_COMPLETED",
            "CANCELED",
            "PICKUP_VERIFICATION"
          ],
          "example": "PICKED_UP"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "The time at which this event occurred. Formatted as an ISO-8601 timestamp.",
          "example": "2024-05-28T00:00:00Z"
        }
      },
      "required": [
        "timestamp",
        "type"
      ]
    },
    "DropoffImageDetails": {
      "properties": {
        "photo_url": {
          "type": "string",
          "description": "A URL to the dropoff photo taken by the driver upon completing the delivery.",
          "example": "http://www.grubhub.com/example.png"
        },
        "photo_capture_time": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp at which the dropoff photo was captured. Formatted as an ISO-8601 timestamp.",
          "example": "2024-05-28T00:00:00Z"
        },
        "photo_capture_location": {
          "$ref": "#/$defs/GeoLocation"
        },
        "photo_expiration_time": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp when the dropoff photo will expire.",
          "example": "2024-05-28T00:00:00Z"
        }
      },
      "required": [
        "photo_capture_location",
        "photo_capture_time",
        "photo_expiration_time",
        "photo_url"
      ]
    },
    "EstimatedEventTimes": {
      "description": "The latest known estimates for the delivery pickup and dropoff times. Will be the actual times if the event has already occurred.",
      "properties": {
        "picked_up": {
          "type": "string",
          "format": "date-time",
          "description": "The estimated pickup time, or the actual pickup time if the pickup has already occurred. Formatted as an ISO-8601 timestamp.",
          "example": "2024-05-28T00:00:00Z"
        },
        "dropped_off": {
          "type": "string",
          "format": "date-time",
          "description": "The estimated drop-off time, or the actual drop-off time if the pickup has already occurred. Formatted as an ISO-8601 timestamp.",
          "example": "2024-05-28T00:00:00Z"
        }
      },
      "required": [
        "dropped_off",
        "picked_up"
      ]
    },
    "GeoLocation": {
      "description": "The last known location of the courier.",
      "properties": {
        "lat": {
          "type": "number",
          "format": "double",
          "description": "The latitude of the location.",
          "example": 41.88320791307697
        },
        "lng": {
          "type": "number",
          "format": "double",
          "description": "The longitude of the location.",
          "example": -87.63142796027925
        }
      },
      "required": [
        "lat",
        "lng"
      ]
    },
    "InTransit": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the assigned courier has departed the restaurant with the delivery.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "PickedUp": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the delivery has been picked up by the assigned courier.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "PickupVerification": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        },
        {
          "type": "object",
          "properties": {
            "pickup_verification_details": {
              "$ref": "#/$defs/PickupVerificationDetails"
            }
          }
        }
      ],
      "description": "An event containing pickup verification information.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "PickupVerificationDetails": {
      "properties": {
        "result": {
          "type": "string",
          "description": "The result of the pickup verification.",
          "example": "SUCCESS"
        },
        "capture_method": {
          "type": "string",
          "description": "The method used to capture the pickup verification.",
          "enum": [
            "MANUAL_ENTRY",
            "QR_SCAN",
            "PHOTO"
          ],
          "example": "QR_SCAN"
        },
        "failure_reason": {
          "type": "string",
          "description": "The reason for a failed pickup verification. Null when result is SUCCESS."
        },
        "attempts_count": {
          "type": "integer",
          "format": "int32",
          "description": "The total number of verification attempts made."
        },
        "photo_url": {
          "type": "string",
          "description": "A URL to the pickup verification photo. Null for code-match events."
        }
      }
    },
    "ProofOfDelivery": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        },
        {
          "type": "object",
          "properties": {
            "dropoff_image_details": {
              "$ref": "#/$defs/DropoffImageDetails"
            }
          }
        }
      ],
      "description": "An event containing proof of delivery information.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "ReturnCompleted": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating that the necessary portion of the delivery's contents have been successfully returned to the pickup location.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "ReturnInitiated": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the delivery is in-transit back to the pickup location in order to return some portion of the delivery's contents.",
      "required": [
        "timestamp",
        "type"
      ]
    },
    "Unassigned": {
      "allOf": [
        {
          "$ref": "#/$defs/DeliveryEvent"
        }
      ],
      "description": "An event indicating the delivery has been unassigned. An unassigned delivery may still be reassigned to another driver later.",
      "required": [
        "timestamp",
        "type"
      ]
    }
  }
}