Pick Provider

Burq API V2 (Alpha)
Base URL: https://api.burqup.com/v2

---

Overview

Retrieve the available quotes for your route and select a provider. You can poll this endpoint until quotes are available. Once quotes are ready, review the options and select the provider that best fits your needs.

This is Step 4 of 5 in the complete delivery flow:

1. Create Orders - Create one or more delivery orders
2. Create Route - Group orders into a multi-stop delivery route
3. Request Quote - Request pricing quotes from available providers
4. Pick Provider ← You are here
5. Dispatch - Dispatch the route with the selected provider

---

Prerequisites

Before picking a provider, ensure you have:

• Completed Step 3: Request Quote
• The route ID from Step 2
• Waited a few seconds for quote generation to complete (or received a webhook notification)

---

Endpoint Details

Endpoint: GET /v2/routes/{route_id}/quotes
Operation ID: ListRouteQuotes
API Reference: List Route Quotes

---

Request

Headers

Header	Value	Required
Content-Type	application/json	Yes
x-api-key	Your API key	Yes

Path Parameters

Parameter	Type	Required	Description
route_id	string	Yes	The route ID from Step 2

Example Request

Bash

curl -X GET "https://api.burqup.com/v2/routes/route_xyz789/quotes" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

---

Response

Success Response (200 OK, status: "COMPLETE")

JSON

{
  "object": "route_quotes",
  "status": "COMPLETE",
  "data": [
    {
      "id": "id01237ay5tfzws8jsc17",
      "object": "route_quote",
      "cost_of_delivery": 1500,
      "burq_fee": 200,
      "provider": "Provider Name",
      "account_id": "acct_xyz789",
      "route_id": "route_xyz789",
      "courier_name": "John Drive",
      "courier_image": "https://example.com/driver-image.jpg",
      "pickup_time": "2026-08-06T11:00:00.000Z",
      "vehicle_id": "veh_1234",
      "expires_at": null
    },
    {
      "id": "id02345b7ay5tfzws8j17",
      "object": "route_quote",
      "cost_of_delivery": 1700,
      "burq_fee": 200,
      "provider": "Provider Name",
      "account_id": "acct_xyz789",
      "route_id": "route_xyz789",
      "courier_name": "John Doe",
      "courier_image": "https://example.com/driver-image2.jpg",
      "pickup_time": "2026-08-06T11:00:00.000Z",
      "vehicle_id": "veh_5642",
      "expires_at": "2026-08-06T12:00:00.000Z"
    }
  ]
}

Important: Save the id field (quote ID) from the response. You'll need it in Step 5: Dispatch.

Success Response (200 OK, status: "PENDING")

JSON

{
    "object": "route_quotes",
    "status": "PENDING",
    "data": null
}

Since requesting a quote is an async operation the status might be PENDING, meaning that the operation is not yet complete. There is a need to poll again after a few seconds.

Response Fields

Field	Type	Description
status	string	PENDING | COMPLETE, showing the status of the request
object	string	Always "route_quotes"
data	array	Actual data

data field:

Field	Type	Description
id	string	Quote ID - Save this for dispatch
object	string	Always "route_quote"
cost_of_delivery	integer	Delivery cost in cents
burq_fee	integer	Burq service fee in cents
provider	string	Provider name
account_id	string	Your merchant account ID
route_id	string	Associated route ID
courier_name	string	Name of the assigned driver (if available)
courier_image	string	Image URL of the driver (if available)
pickup_time	string	Date with time representing the pickup time (if available)
vehicle_id	string	ID of the courier's vehicle (if available)
expires_at	string	Date with time representing the time when the quote expires

---

Multiple Quotes

You may receive multiple quotes if multiple providers are available. Even if the number of quotes is only 1 the structure still sends an array of quotes

Note: The exact response format may depend on your account configuration and available providers.

---

Quote Selection Criteria

When selecting a provider quote, consider:

1. Cost - Compare cost_of_delivery + burq_fee across providers
2. Provider reliability - Consider provider reputation and performance
3. Driver information - Review courier details if available
4. Timing - Ensure the provider can meet your delivery time requirements
5. Special requirements - Verify the provider supports any special delivery needs

---

Polling for Quotes

If quotes aren't ready yet, you may receive a PENDING status. Implement polling with exponential backoff:

Bash

# Example polling logic (pseudo-code)
max_attempts = 10
wait_time = 2  # seconds

for attempt in range(max_attempts):
    response = GET /v2/routes/{route_id}/quotes
    if response.status == 200 and response.status == 'COMPLETE':
        # Quotes are ready!
        break
    else:
        sleep(wait_time)
        wait_time *= 2  # Exponential backoff

Best Practice: Use webhooks instead of polling when possible for better efficiency.

---

Error Handling

Common errors when retrieving quotes:

• route_api_key_test_mode_mismatch - Test mode mismatch between route creation and quote retrieval
• unauthorized - You do not have permission to perform this action
• record_not_found - The route does not exist

See Error Handling for detailed error information.

---

Best Practices

1. Wait before polling - Give quote generation a few seconds before first poll
2. Use webhooks - Configure webhooks to avoid unnecessary polling
3. Implement retry logic - Use exponential backoff when polling
4. Compare quotes - Review all available quotes before selecting
5. Save quote ID - Keep the quote ID for dispatch
6. Act promptly - Quotes may expire; dispatch soon after selection

---

Overview

Next Step

Once you have selected a provider quote and saved the quote ID, proceed to:

Step 5: Dispatch - Dispatch the route with the selected provider

---

Related Documentation

• Step 3: Request Quote - Previous step
• Step 5: Dispatch - Next step
• Route Quotes APIs - Complete quote management guide
• Error Handling - Error codes and handling

---

← Previous: Request Quote | ← Back to Main Documentation | Next: Dispatch →