Create Route

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

Overview

Create a multi-stop delivery route by grouping the orders you created in Step 1. The route will be created in the Driver Management system, and orders will be updated with route and stop identifiers.

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

Create Orders - Create one or more delivery orders
Create Route ← You are here
Request Quote - Request pricing quotes from available providers
Pick Provider - Retrieve and select a provider quote
Dispatch - Dispatch the route with the selected provider

Prerequisites

Before creating a route, ensure you have:

Completed Step 1: Create Orders
One or more order IDs from Step 1
All orders must have the same pickup address

Endpoint Details

Endpoint: POST /v2/routes
Operation ID: CreateRouteV2
API Reference: Create Route

Request

Headers

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

Request Body

Parameter	Type	Required	Description
`order_ids`	array[string]	Yes	Array of order IDs from Step 1
`external_route_ref`	string	No	Your external reference identifier for the route

Example Request

curl -X POST "https://api.burqup.com/v2/routes" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "order_ids": ["ord_abc123", "ord_def456"],
    "external_route_ref": "ROUTE-2024-01-15"
  }'

Response

Success Response (201 Created)

{
  "id": "route_xyz789",
  "object": "route",
  "success": true,
  "status": "draft",
  "merchant_account_id": "acct_xyz789",
  "distance": "5.2",
  "duration": "15",
  "external_route_ref": "ROUTE-2024-01-15",
  "orders": [
    {
      "id": "ord_abc123",
      "object": "order",
      "external_order_ref": "ORDER-001",
      "pickup_address": "123 Main St, New York, NY 10001",
      "dropoff_address": "456 Oak Ave, New York, NY 10002"
    },
    {
      "id": "ord_def456",
      "object": "order",
      "external_order_ref": "ORDER-002",
      "pickup_address": "123 Main St, New York, NY 10001",
      "dropoff_address": "789 Pine St, New York, NY 10003"
    }
  ],
  "stops": [
    {
      "id": "stop_001",
      "object": "stop",
      "route_id": "route_xyz789",
      "sequence": "1",
      "address": "123 Main St, New York, NY 10001",
      "status": "created"
    },
    {
      "id": "stop_002",
      "object": "stop",
      "route_id": "route_xyz789",
      "sequence": "2",
      "address": "456 Oak Ave, New York, NY 10002",
      "status": "created"
    },
    {
      "id": "stop_003",
      "object": "stop",
      "route_id": "route_xyz789",
      "sequence": "3",
      "address": "789 Pine St, New York, NY 10003",
      "status": "created"
    }
  ]
}

Important: Save the id field (route ID) from the response. You'll need it in the next steps.

Response Fields

Field	Type	Description
`id`	string	Unique route identifier - Save this for next steps
`object`	string	Always "route"
`success`	boolean	Indicates if route creation was successful
`status`	string	Route status (e.g., "draft")
`merchant_account_id`	string	Your merchant account ID
`distance`	string	Total distance of the route
`duration`	string	Estimated duration of the route
`external_route_ref`	string	Your external reference (if provided)
`orders`	array	List of orders in the route
`stops`	array	List of stops (pickup + dropoffs) in the route

Route Structure

When you create a route:

The system automatically creates stops for pickup and dropoff locations
Stops are sequenced in an optimal order
The first stop is always the pickup location
Subsequent stops are the dropoff locations

The route will be in draft status until you dispatch it.

Error Handling

Common errors when creating routes:

invalid_order_ids - order_ids must be a non-empty array
orders_already_in_route - Some orders are already assigned to a route
invalid_order_state - Order is not in a state that allows it to be added to a route
orders_different_pickup_address - All orders must have the same pickup address
record_not_found - One or more order IDs don't exist

See Error Handling for detailed error information.

Best Practices

Use external_route_ref - Track routes in your system with your own reference
Group related orders - Create routes with orders that share the same pickup location
Save route ID - Keep the route ID for quote requests and dispatch
Verify order status - Ensure orders are in a valid state before adding to routes
Check route status - Monitor route status using GET /v2/routes/{route_id}

Next Step

Once you have created the route and saved the route ID, proceed to:

Step 3: Request Quote - Request pricing quotes from available providers