Create Delivery

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

Create a delivery, with option to initiate it immediately.

Body Params

initiate

boolean

When set to true, delivery is initiated immediately - the cheapest delivery option will be auto-selected,
and delivery info is sent to delivery provider for fulfillment. No further call to the /initiate_delivery is needed. If manual selection of quote is needed,
set to false and review the returned quotes. Then call /initiate_delivery API with the desired quote ID. Defaults to false if not provided.

pickup_address

string

Address of pickup location. Include all components including street, city, zipcode, and country. Do not include unit number; use pickup_unit property instead. Do not provide if pickup_store_id is provided. Otherwise required.

pickup_unit

string

Unit number of pickup location. Do not provide if pickup_store_id is provided.

pickup_at

date-time

Timestamp for when the items should be picked up. Must be in ISO8601 format. Cannot be both provided with dropoff_at.

pickup_name

string

Individual or company name of pickup location. Optional if pickup_store_id is provided. Otherwise required.

pickup_phone_number

string

Phone number of pickup location. Optional if pickup_store_id is provided. Otherwise required.

pickup_notes

string

Instructions for drivers when picking up delivery items.

dropoff_address

string

Address of dropoff location. Include all components including street, city, zipcode, and country. Do not include unit number; use dropoff_unit property instead. Do not provide if dropoff_store_id is provided. Otherwise required.

dropoff_unit

string

Unit number of dropoff location. Do not provide if dropoff_store_id is provided.

dropoff_name

string

Individual or company name receiving the delivery. Optional if dropoff_store_id is provided. Otherwise required.

dropoff_at

date-time

Timestamp for when the items should be delivered. Must be in ISO8601 format. Cannot be both provided with pickup_at.

dropoff_phone_number

string

Phone number of dropoff location. Optional if dropoff_store_id is provided. Otherwise required.

dropoff_notes

string

Instructions for drivers when dropping off delivery items.

items

array of objects

required

List of items to be delivered.

items*

pickup_store_id

string

ID of a store created through Burq dashboard or API. When provided, store information will be used for any pickup setting not explicitly provided in the request, including address, phone number, name, and notes.

dropoff_store_id

string

ID of a store created through Burq dashboard or API. When provided, store information will be used for any dropoff setting not explicitly provided in the request, including address, phone number, name, and notes.

quote_id

string

ID of a previously generated quote. If not provided, the cheapest quote will be selected automatically.

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.

tip

integer

Tips for the driver. Burq forwards all tips to the delivery providers.

order_value

integer

Total value of all items in the delivery.

contactless_delivery

boolean

Whether delivery should be contactless. Cannot be true if signature is set to true.

signature

boolean

Whether signature should be collected at dropoff. Cannot be true if contactless_delivery is set to true.

connected_account_id

string

Only relevant for Burq Connect merchants. Specify the connected account that you want to create the delivery under. If you are already setting pickup_store_id or dropoff_store_id, you don't need to set this field, as the owner account will be inferred from the store.

required_provider_settings

object

Required provider settings. When quote_id is not provided, providers that don't support the selected settings will be excluded from quote selection. If quote_id is provided, and the provider of the quote does not support the selected provider settings, an error will be returned. Required provider settings are evaluated during reroute. Each provider supports different settings, and excessive requirements may reduce quote availability.

preferred_provider_settings

object

Preferred provider settings do not affect quote availability nor quote selection. When a quote is selected, either explicitly via quote_id, or automatically based on pricing, any supported settings from this configuration will be passed to the provider. Unsupported settings are ignored. Preferred provider settings are evaluated during reroute.

contains_alcohol

boolean

Indicates whether items contain an alcoholic ingredient.

pickup_address_details

object

This object is optional. If provided, all nested fields must be provided. Burq will perform no address validation when this object is provided. The provided address will be sent to providers as is. Merchants are responsible for data validity and accuracy. Note, when this object is provided, you still need to provide a formatted address under pickup_address or pickup_store_id. Additionally, pickup_unit (when applicable) needs to be provided in the top-level field.

dropoff_address_details

object

This object is optional. If provided, all nested fields must be provided. Burq will perform no address validation when this object is provided. The provided address will be sent to providers as is. Merchants are responsible for data validity and accuracy. Note, when this object is provided, you still need to provide a formatted address under dropoff_address or dropoff_store_id. Additionally, dropoff_unit (when applicable) needs to be provided in the top-level field.

Headers

x-api-key

string

required

Burq API key for your account.

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

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
16
1
curl --request POST \
2
     --url https://api.burqup.com/v1/delivery_information \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "pickup_address_details": {
8
    "state": "AL",
9
    "country": "US"
10
  },
11
  "dropoff_address_details": {
12
    "state": "AL",
13
    "country": "US"
14
  }
15
}
16
'


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-11T01:37:38.639Z",
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.