Dispatch

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

Overview

Dispatch the route using the selected provider quote. This initiates the delivery process and assigns the route to the selected provider. Once dispatched, the route status will change from draft to dispatched, and the delivery process begins.

This is Step 5 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 - Retrieve and select a provider quote
5. Dispatch ← You are here

Prerequisites

Before dispatching, ensure you have:

• Completed Step 4: Pick Provider
• The route ID from Step 2
• The quote ID from Step 4
• The route must be in draft status
• The quote must not be expired

Endpoint Details

Endpoint: POST /v2/routes/{route_id}/quotes/{route_quote_id}/dispatch
Operation ID: DispatchRoute
API Reference: Dispatch Route

Request

Headers

Path Parameters

Request Body

No request body is required for this endpoint.

Example Request

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

Response

Success Response (200 OK)

{
  "job_id": "job_dispatch_456",
  "object": "job"
}

Important:

• This endpoint returns immediately with a job_id
• Route dispatch happens asynchronously
• The route status will change from draft to dispatched once processing completes
• You can check the route status using GET /v2/routes/{route_id}

Response Fields

Post-Dispatch Actions

After dispatching, the route enters the delivery process:

1. Route Status - Changes from draft to dispatched
2. Provider Assignment - Route is assigned to the selected provider
3. Driver Assignment - A driver may be assigned (if available)
4. Delivery Tracking - You can track delivery progress via webhooks or API polling

Monitoring Route Status

After dispatch, monitor the route status:

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

The route status will progress through various states:

• draft → dispatched → in_progress → completed (or error states)

Error Handling

Common errors when dispatching:

• route_quote_account_mismatch - Merchant account cannot be different from the merchant account used to generate the provided route quote
• route_quote_already_expired - Provided route quote is already expired
• route_not_found_in_dm - Route not found in Driver Management
• orders_not_found - Some of the orders provided do not exist
• order_part_of_another_route - Some orders are already part of another route
• route_order_already_initiated - Some orders are already initiated
• orders_mismatch_with_stops - The number of stops are lesser than the number of orders pickups and drop-offs
• merchant_account_id_mismatch - All orders do not belong to the same account
• pickup_address_not_same - Pickup address is not same for all orders
• lesser_than_minimum_stops - There should be at least 2 stops in a route

See Error Handling for detailed error information.

Best Practices

1. Dispatch promptly - Quotes may expire; dispatch soon after selection
2. Verify route status - Check route status before dispatching
3. Monitor after dispatch - Track route and order status after dispatch
4. Handle errors gracefully - Implement retry logic for transient errors
5. Use webhooks - Configure webhooks for real-time delivery updates
6. Track job_id - Keep the job_id for tracking (optional, route_id is sufficient)

Next Steps After Dispatch

After successfully dispatching a route:

1. Monitor Route Status - Use GET /v2/routes/{route_id} to track progress
2. Track Individual Orders - Use GET /v2/orders/{order_id} for order-specific updates
3. Handle Webhooks - Process webhook notifications for real-time updates
4. Update Routes - Use route management endpoints if changes are needed

Complete Flow Summary

Congratulations! You've completed the full delivery flow:

1. Create Order(s)
   POST /v2/orders
   → Saved order IDs

2. Create Route
   POST /v2/routes
   → Saved route ID

3. Request Quote
   POST /v2/routes/{route_id}/quotes
   → Quote generation initiated

4. Pick Provider
   GET /v2/quotes/{route_id}
   → Saved quote ID

5. Dispatch
   POST /v2/routes/{route_id}/quotes/{route_quote_id}/dispatch
   → Route dispatched! ✅

Related Documentation

• Step 4: Pick Provider - Previous step
• Route V2 APIs - Complete route management guide
• Order V2 APIs - Complete order management guide
• Error Handling - Error codes and handling

← Previous: Pick Provider | ← Back to Main Documentation