Get Delivery

GEThttps://api.uber.com/v1/customers/{customer_id}/deliveries/{delivery_id}

Access to These APIs May Require Written Approval From Uber

Uber’s APIs are always under development and as such are subject to changes according to our Versioning & Upgrade policy. As part of Uber’s ongoing privacy improvements, we’ve updated our Developer API program with new scope access policies for third party applications. For further information, please refer to our Getting Started guides.

Retrieve the current status of an existing delivery

Request Path Parameters

Name Type Description
customer_id string Unique identifier for the organization. Either UUID or starts with `cus_`.
delivery_id string Unique identifier for the delivery. Always starts with `del_`.

Response Body Parameters

Name Type Description
complete boolean Flag indicating if the delivery is ongoing.
courier CourierInfo Information about the courier. Only present when a delivery is in progress.
courier_imminent boolean Flag is set to true when the courier is 1 minute away from the pickup or dropoff location.
created timestamp (RFC 3339) Date/Time at which the delivery was created.
currency string Three-letter ISO currency code, in lowercase.
deliverable_action DeliverableAction The “happy path” action for the courier to take on a delivery. When used, delivery action can be set to “leave at door” for a contactless delivery. Cannot leave at door when signature or ID verification requirements are applied when creating a delivery. Photo confirmation of delivery will be automatically applied as a requirement to complete drop-off.
dropoff WaypointInfo Dropoff details.
dropoff_deadline timestamp (RFC 3339) When a delivery must be dropped off. This is the end of the dropoff window.
dropoff_eta timestamp (RFC 3339) Estimated drop-off time.
dropoff_ready timestamp (RFC 3339) When a delivery is ready to be dropped off. This is the start of the dropoff window.
fee integer Amount in cents ( ¹/₁₀₀ of currency unit ) that will be charged if this delivery is created.
id string Unique identifier for the delivery (`del_` + tokenize(uuid)).
kind string The type of object being described. Always “delivery”.
live_mode boolean Flag that indicates if this is live mode or test mode.
manifest ManifestInfo A detailed description of what the courier will be delivering.
manifest_items ManifestItem[] List of items being delivered.
pickup WaypointInfo The pickup details for the delivery.
pickup_deadline timestamp (RFC 3339) When a delivery must be picked up by. This is the end of the pickup window.
pickup_eta timestamp (RFC 3339) Estimated time the courier will arrive at the pickup location.
pickup_ready timestamp (RFC 3339) When a delivery is ready to be picked up. This is the start of the pickup window.
quote_id string ID for the Delivery Quote if one was provided when creating this Delivery.
refund RefundData This is an array of the refund information.
related_deliveries RelatedDelivery[] A collection describing other jobs that share an association.
return WaypointInfo The return details for the delivery.
status string The current status of the delivery.

ALLOWED VALUES:
  • pending
  • pickup
  • pickup_complete
  • dropoff
  • delivered
  • canceled
  • returned
tip integer Amount in cents ( ¹/₁₀₀ of currency unit ) that will be paid to the courier as a tip.
tracking_url string This url can be used to track the courier during the delivery.
undeliverable_action string If a delivery was undeliverable, this field will contain the resulting action taken by the courier.
undeliverable_reason string If a delivery was undeliverable, this field will contain the reason why it was undeliverable.
updated timestamp (RFC 3339) Date/Time at which the delivery was last updated.
uuid string Alternative delivery identifier. “Id” field should be used for any identification purposes. “uuid” field is equally unique but loses contextual information (i.e. nothing in this identifier points out that it relates to a delivery). “uuid” is case-sensitive. Value for the “uuid” field is UUID v4 with ‘-’ characters removed.
Response Body Parameters - CourierInfo
Name Type Description
name string Courier’s first name and last initial.
rating float [DEPRECATED] Courier’s rating on a scale of 1.0 to 5.0.
vehicle_type string The type of vehicle the courier is using. Currently support bicycle, car, van, truck, scooter, motorcycle, and walker.
phone_number string The courier’s phone number. This is a masked phone number that can only receive calls or SMS from the dropoff phone number.
location LatLng A latitude and longitude indicating courier’s location.
img_href string A URL to courier’s profile image.
CourierInfo - LatLng
Name Type Description
lat double Latitude.
lng double Longitude.
Response Body Parameters - WaypointInfo
Name Type Description
name string Display name of the person/merchant at the waypoint.
phone_number string The masked phone number of the waypoint.
address string The address of the waypoint.
detailed_address Address Structured address of the waypoint.
notes string Additional instructions at the waypoint location.
seller_notes string Delivery instructions provided by the seller for the courier at the waypoint location.
courier_notes string When a picture is requested as proof-of-delivery, this field contains the notes provided by the courier (e.g. where the items were left).
location LatLng Geographic location (Latitude, Longitude) associated with the waypoint.
verification VerificationProof Details about different verifications that have/will occur at this waypoint and any associated proof.
verification_requirements VerificationRequirement Details about the verification steps that have/must be taken at this waypoint.
external_store_id string Unique identifier used by our Partners to reference a Store or Location
WaypointInfo - Address
Name Type Description
street_address_1 string
street_address_2 string
city string
state string
zip_code string
country string
sublocality_level_1 string
WaypointInfo - LatLng
Name Type Description
lat double Latitude.
lng double Longitude.
WaypointInfo - VerificationProof
Name Type Description
signature SignatureProof Signature information captured.
barcodes BarcodeRequirement[] Barcode values/types that were scanned.
picture PictureProof Picture captured at the waypoint.
identification IdentificationProof Identification information or scanning information captured.
pin_code PincodeProof Pin entry data available after delivery completes.
completion_location LatLng The geographic location (Latitude, Longitude) where the job completes.
VerificationProof - SignatureProof
Name Type Description
image_url string The url of the signature image.
signer_name string The name of the person who signed for the package.
signer_relationship string The relationship of the person who signed for the package to the intended recipient.
VerificationProof - BarcodeRequirement
Name Type Description
value string String value encoded in the barcode.
type string Type of barcode. Valid values: “CODE39”, “CODE39_FULL_ASCII”, “CODE128”, “QR”.
scan_result BarcodeScanResult [optional] barcode scan result
VerificationProof - PictureProof
Name Type Description
image_url string The url of the image taken at the waypoint.
VerificationProof - IdentificationProof
Name Type Description
min_age_verified boolean Flag if ID was successfully verified/scanned.
VerificationProof - PincodeProof
Name Type Description
entered string Value entered during pin verification.
WaypointInfo - VerificationRequirement
Name Type Description
signature boolean [DEPRECATED] Flag for if a signature is required at this waypoint. signature_requirement should be used instead.
signature_requirement SignatureRequirement Signature requirement spec to indicate that a signature must be collected at this waypoint.
barcodes BarcodeRequirement[] Barcode values/types that must be scanned at the waypoint. Number of elements in the array is equal to the number of barcodes that must be scanned.
pincode PincodeRequirement Pincode requirement spec to indicate a delivery requires pincode confirmation upon delivery.
identification IdentificationRequirement Identification scanning/verification requirements for this waypoint.
picture boolean
VerificationRequirement - SignatureRequirement
Name Type Description
enabled boolean Flag for if a signature is required at this waypoint.
collect_signer_name boolean Flag for if the signer’s name is required at this waypoint.
collect_signer_relationship boolean Flag for if the signer’s relationship to the intended recipient is required at this waypoint.
VerificationRequirement - BarcodeRequirement
Name Type Description
value string String value encoded in the barcode.
type string Type of barcode. Valid values: “CODE39”, “CODE39_FULL_ASCII”, “CODE128”, “QR”.
scan_result BarcodeScanResult [optional] barcode scan result
VerificationRequirement - PincodeRequirement
Name Type Description
enabled bool When set to true in POST requests, the delivery will require pincode entry at handoff.
value string The pincode that the customer must present at dropoff. This is a read-only field available in GET requests that will contain the internally generated pincode.
VerificationRequirement - IdentificationRequirement
Name Type Description
min_age integer Minimum age that must be verified for this delivery.
VerificationRequirement - BarcodeScanResult
Name Type Description
outcome enum [optional] barcode scan result. Possible values: INVALID, SUCCESS, SKIPPED
timestamp timestamp (RFC 3339) [optional] timestamp when the barcode was scanned or skipped
Response Body Parameters - ManifestInfo
Name Type Description
reference string Reference that identifies the manifest.
description string [DEPRECATED] A detailed description of what the courier will be delivering. It is better to consume the description of each item in `ManifestItem.name`.
total_value integer Value in cents ( ¹/₁₀₀ of currency unit ) of the items in the delivery. i.e.: $10.99 => 1099.
Response Body Parameters - ManifestItem
Name Type Description
name string (optional) Description of item.
quantity integer (required) Quantity of items.
size string (optional) Approximate size of item. Options are small, medium, large, or xlarge.

If nothing is specified, small will be applied by default.
dimensions Dimensions (optional) Struct that contains dimensions.
price integer (optional) Price in cents ( ¹/₁₀₀ of currency unit ).
weight integer (optional) Weight in grams.
ManifestItem - Dimensions
Name Type Description
length integer [optional] Length in centimeters
height integer [optional] Height in centimeters
depth integer [optional] Depth in centimeters
Response Body Parameters - RelatedDelivery
Name Type Description
id string Unique identifier for the delivery.
relationship string Indicating the nature of the delivery identified in related_deliveries. “original” for the forward leg of the trip, and “returned” for the return leg of the trip.
Response Body Parameters - DeliverableAction
Name Type Description
deliverable_action_meet_at_door string Meet at door delivery. This is the default if “deliverable_action” is not set.

Protocol- Hand off package to customer. Contact customer if necessary. Wait for timer to run out. Fallback on the set “undeliverable_action”
deliverable_action_leave_at_door string This delivery action can be used for a contactless delivery. It cannot be used if signature or PIN or ID verification requirements are applied when creating a delivery.

Protocol- Leave the package at the customer’s door and take a photo. Photo confirmation of delivery will be automatically applied as a requirement to complete drop-off.
Response Body Parameters - RefundData
Name Type Description
id string Unique identifier of the refund request.
created_at number UTC Time i.e. 2023-03-15T04:14:15Z.
currency_code string Three-letter ISO currency code, in uppercase i.e. USD.
total_partner_refund number Total monetary amount that the partner is liable to their customers for in cents ( ¹/₁₀₀ of currency unit ) i.e.:1234.
total_uber_refund number Total monetary amount that Uber will adjust on the billing details report & invoice in cents ( ¹/₁₀₀ of currency unit ) i.e.:1834.
refund_fees RefundFee See the refund fee array object.
refund_order_items RefundOrderItem See the refund order item array object.
RefundData - RefundFee
Name Type Description
fee_code FeeCode See the fee code string object.
value number The amount of the refund fee of the given category.
category Category See the category string object.
RefundFee - FeeCode
Name Type Description
UBER_DELIVERY_FEE string This is the fee collected by Uber Direct from the partner for this given order.
PARTNER_FEE string This is the fee collected by the partner from the end user for this given order.
PARTNER_TAX string This is the tax collected by the partner from the end user for this given order.
RefundFee - Category
Name Type Description
DELIVERY string Delivery related fees.
TAX string Tax related fees.
RefundData - RefundOrderItem
Name Type Description
refund_items RefundItem See the refund item array object.
party_at_fault string “UBER” or “PARTNER”.
partner_refund_amount number The monetary value of items that the partner is liable towards their customers in cents ( ¹/₁₀₀ of currency unit )
uber_refund_amount number The monetary value of items that Uber will adjust on the billing details report & invoice in cents ( ¹/₁₀₀ of currency unit )
reason string A predefined string of refund reason.
RefundOrderItem - RefundItem
Name Type Description
name string The name of the item.
quantity number The quantity of the item.
Refund Payload

Here is an example of a refund Webhook payload.

{
  "created": "2023-03-24T19:02:07.664Z",
  "data": {
    "created_at": "2023-03-24T19:02:05Z",
    "currency_code": "GBP",
    "id": "ffe2c0b4-204f-41ca-9230-2b161b8d6c4b",
    "refund_fees": [
      {
        "category": "DELIVERY",
        "fee_code": "UBER_DELIVERY_FEE",
        "value": 680
      },
      {
        "category": "DELIVERY",
        "fee_code": "PARTNER_FEE",
        "value": 600
      },
      {
        "category": "TAX",
        "fee_code": "PARTNER_TAX",
        "value": 200
      }
    ],
    "refund_order_items": [
      {
        "partner_refund_amount": 1500,
        "party_at_fault": "UBER",
        "reason": "UBER_ITEM_QUALITY_ISSUE",
        "refund_items": [
          {
            "name": "House Tofu-med Firm Regular – 滑豆腐",
            "quantity": 1
          },
          {
            "name": "Donuts",
            "quantity": 2
          }
        ],
        "uber_refund_amount": 1500
      }
    ],
    "total_partner_refund": 2300,
    "total_uber_refund": 2180
  },
  "delivery_id": "del_bQRY2DjpRt-5Yt5_BfDBxw",
  "external_id": "Order 7777",
  "external_store_id": "Store abc",
  "id": "evt_1rntb7I5QGOhacOmM9gEBw",
  "kind": "event.refund_request"
}

Endpoint Specific Errors

Http Status Code Code Message
404 customer_not_found Customer does not exist.
404 delivery_not_found The requested delivery does not exist.
408 request_timeout The request timed out.
500 unknown_error An unknown error happened.
503 service_unavailable Service is currently unavailable.

© 2023 Uber Technologies Inc.