Create 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.

Optional: You can enable automatic route creation by setting batch_settings.routing.auto_route: true. When enabled, routes are automatically created from your orders, allowing you to skip Step 2.

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

Create Orders ← You are here
Create Route - Group orders into a multi-stop delivery route (Skip if auto_route: true)
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 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

Note: This endpoint processes orders asynchronously. You'll receive a batch_id immediately, and order IDs will be available via webhook notification or can be retrieved after processing completes.

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-500 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
- size - Size estimate (small, medium, large, xlarge)

Each Order Object Optional Fields:

external_order_ref - Your external reference identifier
order_value - Total value of all items in the order
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):

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. When enabled, you can skip Step 2: Create Route
- 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/kilometers. Routes will not be created if the delivery radius exceeds this distance

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,
            "size": "large"
          }
        ]
      },
      {
        "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,
            "size": "medium"
          }
        ]
      }
    ],
    "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
      }
    }
  }'

Important:

All orders in the batch must have the same pickup address to be grouped into a route
If auto_route: true is set, routes will be automatically created and you can skip Step 2: Create 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
You'll receive a webhook notification when orders are created (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)

Getting Order IDs and Route IDs

Since batch order creation is asynchronous, you have two options to get the order IDs (and route IDs if auto_route is enabled):

Option 1: Webhook Notification (Recommended)

If you provided a webhook_url in your request, you'll receive a webhook notification when the batch processing completes. The webhook payload will include:

Created order IDs
Route IDs (if auto_route: true was set)

Option 2: Poll for Batch Status

You can poll the batch status endpoint (if available) or use your external_order_ref values to query orders later. Alternatively, wait for the webhook notification.

Note:

If auto_route: false or not set: You'll need the order IDs before proceeding to Step 2: Create Route
If auto_route: true: You'll receive route IDs in the webhook and can skip Step 2, proceeding directly to Step 3: Request Quote

Ensure you have a mechanism to receive and store these IDs.

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
Invalid item size - Use one of: small, medium, large, xlarge
Authentication errors - Verify your API key is correct

See Error Handling for detailed error information.

Best Practices

Use external_order_ref - Track orders in your system with your own reference
Same pickup address - Ensure all orders in a batch share the same pickup address
Configure webhooks - Use webhook_url to receive order IDs automatically when batch processing completes
Use auto_route - Enable auto_route: true to automatically create routes and skip manual route creation
Set routing constraints - Configure max_order_value, max_number_of_orders_per_route, max_route_duration, and max_delivery_radius to control route grouping
Accurate item sizes - Correct sizes help with pricing and provider matching
Set pickup/dropoff times - Provide realistic timing for better route optimization
Batch size - Create batches of reasonable size (e.g., 10-100 orders) for better processing efficiency
Save order IDs - Store order IDs from webhook notifications (needed if not using auto_route)
Handle async processing - Account for the asynchronous nature of batch processing in your workflow

Next Step

Once you have created a batch of orders:

If `auto_route: true` is enabled:

Routes are automatically created during batch processing
You can skip Step 2: Create Route
Proceed directly to Step 3: Request Quote using the route IDs from your webhook notification

If `auto_route: false` or not set:

You need to manually create routes
Ensure you have:
1. Received the order IDs (via webhook or polling)
2. Verified all orders share the same pickup address
Proceed to:

Step 2: Create Route - Group your orders into a multi-stop delivery route

Note: If not using auto_route, you must have the order IDs before proceeding to Step 2. Ensure your webhook handler is ready or implement polling to retrieve order IDs after batch processing completes.