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:

Create Orders - Create one or more delivery orders
Create Route - Group orders into a multi-stop delivery route
Request Quote - Request pricing quotes from available providers
Pick Provider ← You are here
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/quotes/{route_id}
Operation ID: GetRouteQuote
API Reference: Get Route Quote

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

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

Response

Success Response (200 OK)

{
  "id": "quote_abc123",
  "object": "route_quote",
  "cost_of_delivery": 1500,
  "burq_fee": 200,
  "provider": "Provider Name",
  "provider_id": "prov_xyz789",
  "account_id": "acct_xyz789",
  "route_id": "route_xyz789",
  "courier_name": "John Driver",
  "courier_image": "https://example.com/driver-image.jpg"
}

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

Response Fields

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
`provider_id`	string	Provider identifier
`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)

Multiple Quotes

You may receive multiple quotes if multiple providers are available. The response structure may vary:

Single quote - You'll receive one quote object
Multiple quotes - You may receive an array of quotes or need to make multiple requests

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

Quote Selection Criteria

When selecting a provider quote, consider:

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

Polling for Quotes

If quotes aren't ready yet, you may receive an error. 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/quotes/{route_id}
    if response.status == 200:
        # 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:

Quotes not ready - Quote generation is still in progress; poll again later
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

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

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