You may create a Delivery for Burq to persist without actually initiating delivery (that is, having a courier come to the pick up location for the package). Send a POST request to the Create Delivery Information endpoint:
/v1/delivery_information
curl --location --request POST 'https://api.burqup.com/v1/delivery_information' \
--header 'x-api-key: 773e7b38-d83a-4663-9819-abcdeabcde01' \
--header 'Content-Type: application/json' \
--data-raw '{
"pickup_address": "43 E Ohio St, Chicago, IL 60611",
"pickup_phone_number": "+15124439077",
"pickup_name": "Eataly Restaurant",
"pickup_notes": "Please look for package with order label #42123.",
"pickup_unit": "Unit 3211",
"dropoff_address": "233 S Wacker Dr, Chicago, IL 60606",
"dropoff_name": "John Doe",
"dropoff_notes": "Please call upon arrival",
"dropoff_phone_number": "+14342118980",
"dropoff_unit": "Apartment 908",
"order_value": 4489,
"items_description": "Food items",
"external_order_ref": "FantasyStore-Order#42123",
"initiate": false,
"items": [
{ "name": "Brisket Classic", "quantity": 4, "size": "small" }
]
}'
By default, Delivery objects are created in the "request" status that requires client to call a subsequent Initiating Delivery operation in order for a courier to be selected and for items to be delivered.
Delivery can be initiated automatically by setting the Boolean "initiate" property to true in the above request payload.
Quotes Expiration and Delivery Creation
Note that if the Quote referenced in the request payload has expired, a new quote will be generated with a new quote identifier, in which case the fee may change.
If the
quote_idproperty varies in the return payload from thequote_idsubmitted, you may want to alert the end user that the estimated fee may be different.
The response payload will look as follows:
{
"id": "19g68lawsqlrf",
"delivery_type": "asap",
"service": "doordash",
"status": "request",
"tracking_url": "https://burqup.com/track/19g68lawsqlrf",
// Cost of delivery properties
"currency": "USD",
"fee": 869,
"payment_amount": 869,
"tip": 300,
"upsell": null,
"subsidized": null,
// General delivery properties
"created_at": "2022-11-25T17:47:37.000Z",
"cancellation_reason": null,
"external_order_ref": "FantasyStore-Order#42123",
"order_value": 4489,
"proof_of_delivery": [],
"quote_id": "19g68lawsqlqj",
"signature": null,
"status_history": [],
"store_id": null,
"test_mode": true,
"updated_at": "2022-11-25T17:47:37.000Z",
"vehicle": null,
// Pickup and dropoff properties
"pickup_at": null,
"pickup_address": "43 E Ohio St, Chicago, IL 60611, USA",
"pickup_eta": "2022-11-25T18:00:00.000Z",
"pickup_name": "Eataly Restaurant",
"pickup_notes": "Please look for package with order label #42123.",
"pickup_phone_number": "15124439077",
"pickup_unit": "Unit 3211",
"dropoffs": [
{
"dropoff_at": null,
"dropoff_address": "233 S Wacker Dr, Chicago, IL 60606, USA",
"dropoff_eta": "2022-11-25T18:30:00.000Z",
"dropoff_name": "John Doe",
"dropoff_notes": "Please call upon arrival",
"dropoff_phone_number": "14342118980",
"dropoff_unit": "Apartment 908",
}
],
// Delivery items
"items_description": "Food items",
"items": [
{
"name": "Brisket Classic",
"quantity": 4,
"size": "small"
}
],
// Driver properties
"courier_name": null,
"courier_img": null,
"courier_phone_number": null,
"courier_vehicle_type": null,
"courier_location_lat": null,
"courier_location_lng": null
}
Understanding Cost of Delivery Properties
Cost-of-delivery properties describe properties from the response that can help you to understand the delivery cost and display the appropriate amount to your end users. Please note all properties below are in "cents" and in the currency from the currency property.
| Property Name | Description | Nullable |
|---|---|---|
| currency | The currency in which you will be charged for the delivery. Currently only "USD" is supported. | No |
| payment_amount | The amount (excluding tips) that Burq will charge your payment method. This includes cost charged by your delivery provider and any applicable Burq processing fee. | No |
| tip | The amount of tips that will be paid to the driver by the requesting merchant. Please note tip is charged in addition to the payment_amount property. | Yes |
| fee | This amount is usually the same as payment_amount unless your account has configured "subsidy" and "upsell". If configured, this property will include the final amount after subsidy and upsell adjustments (excluding tips). Note this property is meant to make it easier for you to display delivery cost to your end users. It does not affect how much you are actually charged. Please see "subsidized" and "upsell" fields below for details. | No |
| upsell | This is the calculated upsell amount. This property is only set if your account has upsell configured. This amount is included in the "fee" property but not the "payment_amount" property. This property does not affect how much you are actually charged. | Yes |
| subsidized | This is the calculated subsidized amount. This property is only set if your account has subsidy configured. This amount is included in the "fee" property but not the "payment_amount" property. This property does not affect how much you are actually charged. | Yes |
Understanding Delivery Status Transitions
The "status" property describes the current state of a delivery. Generally, a delivery lifecycle starts with one of the "initial statuses", before going through various "in-transit statuses", and finally terminating in either one of the "fulfilled statuses" or "failed/canceled statuses".
Initial Statuses
Deliveries that are created but not initiated have the request status. ASAP deliveries that have been initiated have the initial status of delivery_created. Lastly, scheduled deliveries are initialized with the scheduled status.
In-transit Statuses
A delivery goes into the "in-transit statues" usually as soon as a driver is assigned. Below is the full list of statuses that a typical delivery may go through. Please note that not all providers inform Burq of every status transition listed below. Therefore, it's quite common for deliveries to "skip" certain statuses during their lifecycle.
driver_assigned- Driver has been assigned to the delivery.enroute_pickup- Driver is en route to the pickup location.arrived_at_pickup- Driver has arrived at the pickup location.pickup_complete- Driver has collected all items from the pickup location.enroute_dropoff- Driver is en route to the dropoff location.arrived_at_dropoff- Driver has arrived at the dropoff location.dropoff_complete- Driver has dropped off all items at the dropoff location.
Occasionally, you may also observe the driver_not_assigned status. This may happen if provider is in the middle of changing driver assignment.
Fulfilled Statuses
When a delivery has been completed, its status transitions into the delivered status. This is the end of lifecycle for most deliveries. Occasionally, if Burq receives a dispute from the requesting merchant to dispute the delivery, we may transition the delivery into the disputed status.
Canceled Statuses
A delivery can be canceled by the merchant (requesting merchant), Burq, or the provider. The statuses below represent a delivery has been canceled by the respective party. These statuses are terminal statuses.
provider_canceledcustomer_canceledburq_canceled
Failed Statuses
Occasionally, deliveries don't go as planned. For example, a driver may be unable to contact the end user to complete the dropoff. In these situations, Burq will transition the delivery into one of the failed statuses below:
failed- The delivery was created in Burq but was not sent to delivery provider. This can happen because the account's payment method is declined, or because the provider is unable to accept the delivery due to technical or capacity issues. Any payment collected for a. failed delivery is fully refunded to the merchant.enroute_to_return- Driver is unable to complete the delivery and is on their way back to the original pickup location to return the items.returned- Driver is unable to complete the delivery and has returned all items back to the pickup location.
Status History
The status_history shows the a list of statuses and the date the status was created. See the documentation on Using Webhooks for more details.
Understanding Driver Information
Once a driver has been assigned you will be able to track their progress through the properties courier_location_lat and courier_location_lng. These properties indicate the driver's last reported location.
You can also use the courier_phone_number property to contact the driver directly.
Availability of Courier Related Properties
Note that these courier related properties are not available until Delivery has been assigned a driver. Furthermore, not all courier properties are provided by every delivery provider.