Initiate Delivery

post https://api.burqup.com/v1/initiate_delivery

Initiate a delivery. Once a delivery is initiated, provider may begin fulfillment, and cancelation may no longer be possible.

Responses

Response body

object

string

required

Unique identifier for the delivery.

object

string

required

Name of the API resource.

delivery

delivery_type

string

required

Describes whether delivery is scheuduled for a future time.

asap scheduled

provider

object

required

The information of the service provider

string

required

Service provider Id of the delivery.

name

string

required

Name of the selected delivery provider.

status

string

required

Status of the delivery.

  * `request` - initial state of Delivery when it is first requested.

  * `delivery_created` - Status of the delivery after "initiate" delivery has been called.

  * `driver_not_assigned` - A driver has not been assigned to the delivery.

  * `driver_assigned` - A driver has been assigned to the delivery.

  * `enroute_pickup` - The driver is en route to the pick up location.

  * `arrived_at_pickup` - The driver has arrived at the pick up location.

  * `pickup_complete` - The items have been picked up from the pick up location.

  * `enroute_dropoff` - The delivery is en route to the drop off location.

  * `arrived_at_dropoff` - The delivery has arrived at the drop off location.

  * `dropoff_complete` - All drop offs are complete.

  * `delivered` - Courier has completed the drop offs.

  * `provider_canceled` - The delivery provider canceled the delivery.

  * `customer_canceled` - The delivery was canceled by the customer.

  * `burq_canceled` - The delivery was canceled by Burq for internal reasons.

  * `failed` - an error occurred during the process of delivery.

  * `disputed` - Indicates that the customer has disputed the delivery.

  * `enroute_to_return` - indicates that the items are enroute to their original pick up location for the purpose of being returned.

  * `returned` - Delivery was canceled and a new delivery created to return items to sender.

driver_assigned enroute_pickup arrived_at_pickup pickup_complete enroute_dropoff arrived_at_dropoff dropoff_complete request scheduled delivery_created driver_not_assigned delivered disputed provider_canceled customer_canceled burq_canceled failed enroute_to_return returned

tracking_url

string

URL of the tracking page. This page can be sent to the end user or used internally by the merchant.

currency

string

required

Currency of all monetary amounts related to this delivery, in ISO4217 format.

payment_amount

integer

required

Total before tip for the delivery. This amount includes delivery provider fees and any applicable Burq fees.

tip

integer

Tips are 100% forwarded to the delivery provider.

fee

integer

required

For merchants that use the quote workflow feature, this property describes the "delivery cost" that should be displayed to the end user. This property is only relevant for quote workflow merchants. It is not the payment amount that Burq charges for the delivery.

created_at

date-time

required

Timestamp for when the delivery was created.

cancellation_reason

string

Cancelation reason as provided by the delivery provider. Only relevant for provider-canceled deliveries.

external_order_ref

string

Merchant-provided delivery identifier. Commonly used for merchants to cross-reference deliveries from Burq API with their own system. When provided, this is also used as "order number" and used by drivers to find the right order at pickup location.

order_value

integer

Total value of all items in the delivery.

proof_of_delivery

array of strings

required

Image urls uploaded by drivers for proof of delivery. An empty array is returned when there is none. Burq automatically requests proof of delivery photos with provider whenever possible.

proof_of_delivery*

proof_of_pickup

array of strings

required

Image urls uploaded by drivers for proof of pickup. An empty array is returned when there is none. Burq requests pickup proof photos from the provider when proof of pickup was requested.

proof_of_pickup*

contactless_requested

string

required

Indicates whether contactless delivery was requested.

signature_requested

string

required

Indicates whether signature was requested.

undeliverable_action_requested

string

required

Indicates whether signature was requested.

quote_id

string

required

ID of the associated Quote object.

contains_alcohol

string

required

Indicates whether items contain an alcoholic ingredient.

signature

string

URL of signature image uploaded by driver. Only applicable when signature is requested.

status_history

array of objects

Status history of the delivery.

status_history

object

status

string

required

A delivery status. Please see the top-level status property for possible values.

time

date-time

required

Time when the delivery transitioned out of this status.

pickup_store_id

string

Burq store ID of requested pickup location.

dropoff_store_id

string

Burq store ID of requested dropoff location.

test_mode

boolean

required

Indicates the delviery was generated by the test-mode API Key.

updated_at

date-time

required

Timestamp for when the Delivery was last updated.

vehicle

string

Vehicle type requested by the merchant.

pickup_at

date-time

Timestamp for when the items should be picked up. Must be in ISO8601 format.

pickup_address

string

required

Address of pickup location.

pickup_eta

date-time

Estimated time the courier will arrive at the pickup location, in ISO8601 format.

pickup_name

string

required

Individual or company name of pickup location.

pickup_notes

string

Instructions for driver to access the pickup location.

pickup_phone_number

string

required

Phone number for driver to contact pickup location.

pickup_unit

string

Unit number of pickup location.

dropoffs

array of objects

required

A single-element array that contains the dropoff information for this delivery. For the time being, this property will always return an array of one element.

dropoffs*

object

dropoff_address

string

required

Address of dropoff location.

dropoff_at

date-time

Timestamp for when the items should be delivered.

dropoff_eta

date-time

Estimated time driver will arrive at dropoff location, in ISO8601 format.

dropoff_name

string

required

Individual or company name receiving the delivery.

dropoff_notes

string

Instructions for drivers when dropping off delivery items.

dropoff_phone_number

string

required

Phone number of dropoff location.

dropoff_unit

string

Apartment or unit number of dropoff location.

dropoff_address_city

string

Dropoff city of the delivery.

dropoff_address_state

string

Dropoff state of the delivery.

dropoff_address_street

string

Dropoff street of the delivery.

items

array of objects

required

List of items to be delivered.

items*

object

name

string

required

Description of the item.

quantity

string

required

Quantity of the item.

size

string

required

Estimate of the size of an item being delivered that factors into the handling and pricing.

      * `small` - The order item can be easily carried with one hand, e.g. a shoe box.

      * `medium` - You need a bag to carry the order item, e.g. a retail bag.

      * `large` - Need two hands to carry the order item, e.g. a computer monitor.

      * `xlarge` - The order item fits in the trunk of a car or multiple trips are necessary to transport the order item from the vehicle to its destination.

small medium large xlarge

courier_name

string

Name of the driver.

courier_img

string

Image URL of the driver. Not all providers share driver image.

courier_phone_number_for_customer

string

Driver's phone number. This phone number can be accessed by the dropoff phone number provided for this delivery.

courier_phone_number_for_store

string

Driver's phone number. This phone number can be accessed by the pickup phone number provided for this delivery.

masked_courier_phone_number_for_store

string

Driver's masked phone number. This phone number can only be accessed by the pickup phone number provided for this delivery.

courier_phone_number_for_store_pin_code

string

A pin code required to enter while making a phone call to the driver's phone number. Not all providers share this information.

courier_vehicle_type

string

Driver's vehicle type. Not all providers share this information.

courier_location_lat

integer

Latitude of driver's current location.

courier_location_lng

integer

Longitude of driver's current location.

reroute

object

required

An object that contains the reroute information of the delivery.

reroute_status

string

required

Reroute state of the delivery.

not_applicable provider_search rerouted not_reroutable disabled_for_account

not_rerouted_reason

string

Reason why delivery cannot be rerouted. Only relevant when reroute status is not_reroutable.

no_alternative_provider alternative_too_expensive items_not_available customer_cancelled already_picked_up restaurant_closed merchant_requested merchant_disabled_auto_reroute already_rerouted_too_many_times failed_to_create_quotes failed_to_create_reroute_delivery already_rerouted merchant_disabled_manual_reroute

new_delivery_id

string

Id of the rerouted delivery.

byopk_cost_factors

array of objects

Breakdown of cost factors that will be billed to the merchant directly by the provider. This object is only relevant when provider credentials are provided by the merchant.

byopk_cost_factors

object

name

string

required

Describes the nature of the cost factor.

amount

integer

required

Describes the amount of the cost factor.

account_id

string

required

Owner account of the delivery.

Language


xxxxxxxxxx
1
curl --request POST \
2
     --url https://api.burqup.com/v1/initiate_delivery \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'


xxxxxxxxxx
91
}
1
{
2
  "id": "string",
3
  "object": "delivery",
4
  "delivery_type": "asap",
5
  "provider": {
6
    "id": "string",
7
    "name": "string"
8
  },
9
  "status": "driver_assigned",
10
  "tracking_url": "string",
11
  "currency": "string",
12
  "payment_amount": 0,
13
  "tip": 0,
14
  "fee": 0,
15
  "created_at": "2025-04-09T08:01:58.813Z",
16
  "cancellation_reason": "string",
17
  "external_order_ref": "string",
18
  "order_value": 0,
19
  "proof_of_delivery": [
20
    "string"
21
  ],
22
  "proof_of_pickup": [
23
    "string"
24
  ],
25
  "contactless_requested": "string",

200The request was successful.

400Errors under status code 400. See error examples under the "Response" tab on right. Note examples are for reference only. Field values are neither exhaustive nor api-version-controlled.

403Errors under status code 403. See error examples under the "Response" tab on right. Note examples are for reference only. Field values are neither exhaustive nor api-version-controlled.

404Errors under status code 404. See error examples under the "Response" tab on right. Note examples are for reference only. Field values are neither exhaustive nor api-version-controlled.