Create Delivery

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

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.

Create a delivery between two addresses.

Request Path Parameters

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

Request Body Parameters

Name Type Description
dropoff_address string - Structured Address (required) For single string, format is : “Street Address, City, State, Zip”
dropoff_name string (required) Name of the place where the courier will make the dropoff.
dropoff_phone_number string (required) The phone number of the dropoff location. Should be in e164 format (eg. “+13235550000”).
manifest string (optional) Details about the delivery - Name, Quantity & Size of the package.

[SOON TO BE DEPRECATED] manifest_items should be used instead.

Note: Resolve manifest error by including manifest_items in the request.
manifest_items ManifestItem[] (required) List of items being delivered.
pickup_address string - Structured Address (required) For single string, format is : “Street Address, City, State, Zip”
pickup_name string (required) Name of the place where the courier will make the pickup.
pickup_phone_number string (required) The phone number of the pickup location. Should be in e164 format (eg. “+13235550000”).
deliverable_action DeliverableAction Specify the “happy path” action for the courier to take on a delivery.

Note: If not set then the default value is "meet at door"
dropoff_business_name string Business name of the dropoff location.
dropoff_latitude double Dropoff latitude coordinate.
dropoff_longitude double Dropoff longitude coordinate.
dropoff_notes string Additional instructions for the courier at the dropoff location. Max 280 characters.
dropoff_seller_notes string Additional instructions provided by the merchant for the dropoff. Max 280 characters.
dropoff_verification VerificationRequirement Verification steps (i.e. barcode scanning) that must be taken before the dropoff can be completed.
manifest_reference string Reference that identifies the manifest. Use this to connect a delivery to corresponding information in your system.
external_id string Additional reference to identify the manifest. To be used by aggregators, POS systems, and other organization structures which have an internal reference in addition to the manifest_reference used by your sub-account.
manifest_total_value integer Value in cents ( ¹/₁₀₀ of currency unit ) of the items in the delivery. i.e.: $10.99 => 1099.
pickup_business_name string Business name of the pickup location.
pickup_latitude double Pickup latitude coordinate.
pickup_longitude double Pickup longitude coordinate.
pickup_notes string Additional instructions for the courier at the pickup location. Max 280 characters.
pickup_verification VerificationRequirement Verification steps (i.e. barcode scanning) that must be taken before the pickup can be completed.
quote_id string The ID of a previously generated delivery quote.
undeliverable_action UndeliverableAction Specify the “unhappy path” action for the courier to take on a delivery once a normal delivery attempt is made and a customer is not available.

Note: If not set then the default value is "return"
pickup_ready_dt timestamp (RFC 3339) Beginning of the window when an order must be picked up. Must be less than 30 days in the future.
pickup_deadline_dt timestamp (RFC 3339) End of the window when an order may be picked up. Must be at least 10 mins later than pickup_ready_dt and at least 20 minutes in the future from now.
dropoff_ready_dt timestamp (RFC 3339) Beginning of the window when an order must be dropped off. Must be less than or equal to pickup_deadline_dt .
dropoff_deadline_dt timestamp (RFC 3339) End of the window when an order must be dropped off. Must be at least 20 mins later than dropoff_ready_dt and must be greater than or equal to pickup_deadline_dt.
requires_dropoff_signature boolean [DEPRECATED] Flag to indicate this delivery requires signature capture at dropoff.
requires_id boolean Flag to indicate this delivery requires ID check (minimum age) at dropoff
tip integer Amount in cents ( ¹/₁₀₀ of currency unit ) that will be paid to the courier as a tip.
idempotency_key string A key which is used to avoid duplicate order creation with identical idempotency keys for the same account. The key persists for a set time frame, defaulting to 6 hours
external_store_id string (Optional) Unique identifier used by our Partners to reference a Store or Location
return_verification VerificationRequirement Verification steps (barcode scanning, picture, or signature) that must be taken before the return can be completed.
Request Body Parameters - Structured Address
Name Type Description
street_address array[string] Array of street address elements. For example: [“2000 Ocean Ave", “Floor 2” ]
city string
state string
zip_code string
country string (optional)
Request 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
Request 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.
Request Body Parameters - 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 field will be ignored in the CreateDelivery requests, and the pin code is internally generated when this requirement is present.
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
Request Body Parameters - UndeliverableAction
Name Type Description
leave_at_door string Once a normal delivery attempt is made and a customer is not available. This action requests the courier to leave the package at dropoff location.

Note1: It cannot be set to “leave at door” when signature or PIN or ID verification requirements are applied when creating a delivery.
Note2: A photo confirmation of delivery will be automatically applied as a requirement to complete the drop-off.
return string Once a normal delivery attempt is made and a customer is not available. This action requests the courier to return the package back to the pickup location.

Note: Even if “deliverable_action” was set as “leave at door” and courier feels it is not okay then the package can be returned back to the pickup location.
discard string Discard option will allow the courier to keep/throw away the package if they are unable to deliver the package.

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 indicating if the courier is close to 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.
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.
external_id string An ID for an account as stored in an external system.
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.
related_deliveries RelatedDelivery[] A collection describing other jobs that share an association. i.e.: a return delivery.
status string The current status of the delivery. Always pending when the delivery is created.
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 (unauthenticated page).
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.
return WaypointInfo The return details for the delivery.

Summary of order identifiers above

ID Description Use case
External Order ID (optional) Generated by: Merchant Use your own ID structure
UUID Generated by: Uber. Unique order identifier created for every delivery. When you need a single unique identifer
Abbreviated UUID Generated by: Uber. Last 5 digits of the UUID. Shown as “Order ID” in Courier app
Tokens Generated by: Uber. We use three order tokens that track an order through 3 potential stages: Quote, delivery, and return. A token prefixed with dqt_ indicates the order is in the quote stage (A quote has been generated, but a delivery has not been created). del_ indicates the delivery stage (The delivery is in-progress), and ret_ indicates the order is in the return stage (The items are being returned to the merchant). You can track an order through its stages by referencing the same token, but prepending with the token identifier (e.g. dqt_XXXXXXXX becomes del_XXXXXXXX). These tokens are unique.
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.

Endpoint Specific Errors

Http Status Code Code Message
409 duplicate_delivery An active delivery like this already exists. A pointer to the other delivery is provided.
400 invalid_params The parameters of your request were invalid.
400 unknown_location The specified location was not understood.
400 address_undeliverable The specified location is not in a deliverable area.
400 address_undeliverable_limited_couriers The specified location is not in a deliverable area at this time because all couriers are currently busy.
400 expired_quote The price quote specified has expired.
400 used_quote TThe price quote specified has expired.
400 mismatched_price_quote The price quote specified doesn’t match the delivery.
400 missing_payment Your account’s payment information has not been provided.
400 pickup_ready_time_not_specified Pickup ready time must be specified when passing in pickup/dropoff windows.
400 pickup_window_too_small The pickup window needs to be at least 10 minutes long.
400 dropoff_deadline_too_early The dropoff deadline needs to be at least 20 minutes after the dropoff ready time.
400 dropoff_deadline_before_pickup_deadline The dropoff deadline needs to be after the pickup deadline.
400 dropoff_ready_after_pickup_deadline The dropoff ready time needs to be at or before the pickup deadline.
400 pickup_ready_too_early The pickup ready time cannot be in the past.
400 pickup_deadline_too_early The pickup deadline time needs to be at least 20 minutes from now.
400 pickup_ready_too_late The pickup ready time needs to be within the next 30 days.
402 customer_suspended Your account is passed due. Payment is required.
403 customer_blocked Your account is not allowed to create deliveries.
429 customer_limited Your account’s limits have been exceeded.
500 unknown_error An unknown error happened.

© 2023 Uber Technologies Inc.