Create and dispatch orders

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

Overview

Create multiple delivery orders in a single batch request. This endpoint accepts 1-300 orders that will be processed asynchronously. Orders must have the same pickup address to be grouped into a route.

This is as single step flow for a complete delivery.

Prerequisites

Before creating orders, ensure you have:

A valid Burq API key (see Authentication)
Pickup and dropoff addresses ready for all orders
Order details (items, values, etc.) for all orders
All orders must share the same pickup address

Endpoint Details

Endpoint: POST /v2/orders/create
Operation ID: CreateBatchOrdersV2
API Reference: Create Batch Orders V2

Request

Headers

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

Request Body

The request body contains an orders array with 1-300 order objects. Each order follows the same schema as the single order creation endpoint.

Request Body Structure:

orders (array, required) - Array of 1-300 order objects

Each Order Object Required Fields:

pickup.address - Address for the pickup location
pickup.name - Individual or company name of pickup location
pickup.phone_number - Phone number for driver to contact at pickup
dropoff.address - Address of dropoff location
dropoff.name - Individual or company name receiving the order
dropoff.phone_number - Phone number of dropoff location
items - List of items to be delivered (array)
- name - Description of the item
- quantity - Quantity of the item

Each Order Object Optional Fields:

external_order_ref - Your external reference identifier
order_value - Total value of all items in the order (in cents)
pickup.at - Timestamp for when items should be picked up (ISO8601 format)
dropoff.at - Timestamp for when items should be delivered (ISO8601 format)
tip - Tips for the driver
request_contactless - Whether delivery should be contactless
request_signature - Whether signature should be collected at dropoff

Request Body Optional Fields:

webhook_url - HTTPS URL for receiving webhook notifications about batch processing status
batch_settings - Batch processing settings, including automatic route creation

Batch Settings (batch_settings): this is where the difference from Manual Dispatch happens

The batch_settings object allows you to configure automatic route creation and routing constraints:

routing (object) - Routing configuration
- auto_route (boolean) - If true, automatically creates routes from orders
- max_order_value (integer) - Maximum total order value per route. Routes will not be created if the combined order value exceeds this amount
- max_number_of_orders_per_route (integer) - Maximum number of orders per route. Routes will not be created with more orders than this limit
- max_route_duration (integer) - Maximum route duration in seconds. Routes will not be created if the estimated duration exceeds this value
- max_delivery_radius (integer) - Maximum delivery radius in miles. Routes will not be created if the delivery radius exceeds this distance
quoting (object) - Quoting configuration
- auto_quote (boolean) - If true, automatically requests quotes
- retry_window (integer) - Maximum total retry time window in seconds for automatic quote retries. E.g., 14400 = 4 hours.
- retry_interval (integer) - Interval in seconds between automatic quote retry attempts. E.g., 3600 = 1 hour.
- quote_preference (cheapest | most_reliable) - Quote selection preference. 'cheapest' selects the lowest-price quote; 'most_reliable' selects the highest-reliability quote. Overrides stored merchant preferences for this request.
dispatching (object) - Dispatching configuration
- auto_dispatch (boolean) - If true , automatically dispatch the orders

Example Request

curl -X POST "https://api.burqup.com/v2/orders/create" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "orders": [
      {
        "external_order_ref": "ORDER-001",
        "order_value": 5000,
        "pickup": {
          "address": "123 Main St, New York, NY 10001",
          "name": "Burq Store",
          "phone_number": "+1234567890",
          "at": "2024-01-15T12:00:00Z"
        },
        "dropoff": {
          "address": "456 Oak Ave, New York, NY 10002",
          "name": "John Doe",
          "phone_number": "+1987654321",
          "at": "2024-01-15T14:00:00Z"
        },
        "items": [
          {
            "name": "Pizza",
            "quantity": 2
          }
        ]
      },
      {
        "external_order_ref": "ORDER-002",
        "order_value": 3000,
        "pickup": {
          "address": "123 Main St, New York, NY 10001",
          "name": "Burq Store",
          "phone_number": "+1234567890",
          "at": "2024-01-15T12:00:00Z"
        },
        "dropoff": {
          "address": "789 Pine St, New York, NY 10003",
          "name": "Jane Smith",
          "phone_number": "+1555555555",
          "at": "2024-01-15T14:00:00Z"
        },
        "items": [
          {
            "name": "Burger",
            "quantity": 1
          }
        ]
      }
    ],
    "webhook_url": "https://your-webhook-url.com/batch-status",
    "batch_settings": {
      "routing": {
        "auto_route": true,
        "max_order_value": 2400,
        "max_number_of_orders_per_route": 5,
        "max_route_duration": 28800,
        "max_delivery_radius": 30
        },
        "quoting": {
          "auto_quote": true,
          "quote_preference": "cheapest"
         },
         "dispatching": {
           "auto_dispatch": true
         }
    }
  }'

Important:

All orders in the batch must have the same pickup address to be grouped into a route

Response

Success Response (202 Accepted)

{
  "batch_id": "batch_abc123",
  "object": "batch",
  "status": "queued",
  "orders_count": 2,
  "created_at": "2024-01-15T10:00:00Z"
}

Important:

This endpoint returns immediately with a batch_id
Order creation happens asynchronously. Please refer to webhook batch events for a complete list.
You'll receive a webhook notification when orders are created, quote is selected and order is dispatched (if webhook_url is provided)
Order IDs will be included in the webhook payload or can be retrieved using the batch ID

Response Fields

Field	Type	Description
`batch_id`	string	Unique batch identifier - Use this to track batch status
`object`	string	Always "batch"
`status`	string	Batch status (initial status is "queued")
`orders_count`	integer	Number of orders in the batch
`created_at`	string	Timestamp when the batch was created (ISO8601 format)

Batch Size Limits

Minimum: 1 order per batch
Maximum: 300 orders per batch

For routes with more than 300 orders, create multiple batches and combine the order IDs from all batches when creating the route.

Error Handling

Common errors when creating batch orders:

invalid_orders_count - The orders array must contain between 1 and 500 orders
invalid_webhook_url - The webhook_url must be a valid URL
webhook_url_not_https - The webhook_url must use HTTPS protocol
Missing required fields - Ensure all required fields are provided for each order
Invalid addresses - Verify pickup and dropoff addresses are valid
Authentication errors - Verify your API key is correct

See Error Handling for detailed error information.