GuidesAPI Reference
Log In
API Reference

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

HeaderValueRequired
Content-Typeapplication/jsonYes
x-api-keyYour API keyYes

Path Parameters

ParameterTypeRequiredDescription
route_idstringYesThe route ID from Step 2

Example Request

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")

{
  "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")

{
    "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

FieldTypeDescription
statusstringPENDING | COMPLETE, showing the status of the request
objectstringAlways "route_quotes"
dataarrayActual data

data field:

FieldTypeDescription
idstringQuote ID - Save this for dispatch
objectstringAlways "route_quote"
cost_of_deliveryintegerDelivery cost in cents
burq_feeintegerBurq service fee in cents
providerstringProvider name
account_idstringYour merchant account ID
route_idstringAssociated route ID
courier_namestringName of the assigned driver (if available)
courier_imagestringImage URL of the driver (if available)
pickup_timestringDate with time representing the pickup time (if available)
vehicle_idstringID of the courier's vehicle (if available)
expires_atstringDate 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:

# 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

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

Updated 7 days ago

Updated 7 days ago