Create Order

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

Overview

Burq offers two ways to create orders. They accept the same order schema — the difference is how the response is delivered.

If you want a synchronous flow, use POST /v2/orders. It returns the created order in the response, so no webhook handling is required.

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:

1. Create Orders ← You are here
2. Create Route - Group orders into a multi-stop delivery route (Skip if auto_route: true)
3. Request Quote - Request pricing quotes from available providers
4. Pick Provider - Retrieve and select a provider quote
5. 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
• For batch requests: all orders must share the same pickup address
• For batch requestsa webhook subscription configured on your account, so you receive the resulting order IDs

Request

Headers

Both endpoints use the same headers.

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.

Order Object

Both endpoints accept the same order schema. POST /v2/orders takes a single order object as the request body; POST /v2/orders/create takes an array of them under orders.

Batch 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):

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

Option 1: Create a Single Order (Synchronous)

Endpoint: POST /v2/orders
Operation ID: CreateOrdersV2
API Reference: Create Orders V2

Example Request

curl -X POST "https://api.burqup.com/v2/orders" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "external_order_ref": "ORDER-001",
  "order_value": 5000,
  "pickup": {
    "address": "123 Main St, New York, NY 10001",
    "name": "Burq Store",
    "phone_number": "+1234567890"
  },
  "dropoff": {
    "address": "456 Oak Ave, New York, NY 10002",
    "name": "John Doe",
    "phone_number": "+1987654321"
  },
  "items": [
    {
      "name": "Pizza",
      "quantity": 2,
      "unit_price": 100,
      "length": 100,
      "width": 90,
      "height": 80,
      "weight": 200
    }
  ]
}'

Response

Success Response (201 Created)

{
    "id": "o_01kzdnk8tsegc8men1qgdnp123",
    "object": "order",
    "test_mode": true,
    "account_id": "16lk5kkwl9fq1234",
    "platform_account_id": "acct_16lk5kkwl9f12345",
    "pickup": {
        "address": "1-23 Main St, Queens, NY 10001, USA",
        "latitude": 40.762363,
        "longitude": -73.8313912,
        "unit": null,
        "phone_number": "1234567890",
        "name": "Burq Store",
        "contact_email": null,
        "notes": null,
        "store_id": null,
        "at": null,
        "window": null
    },
    "dropoff": {
        "address": "456 Oak Ave, Staten Island, NY 10306, USA",
        "latitude": 40.5604549,
        "longitude": -74.1158896,
        "unit": null,
        "phone_number": "1987654321",
        "name": "John Doe",
        "contact_email": null,
        "notes": null,
        "store_id": null,
        "at": null,
        "window": null
    },
    "external_order_ref": "ORDER-001",
    "external_route_ref": null,
    "external_stop_seq": null,
    "order_value": 5000,
    "tip_amount": 0,
    "created_at": "2026-08-07T08:31:52.665Z",
    "updated_at": "2026-08-07T08:31:52.665Z",
    "order_token": "token",
    "checkout_url": "https://website-checkout.burqup.com?order_token=token",
    "items": [
        {
            "name": "Pizza",
            "quantity": 2,
            "unit_price": 100,
            "description": null,
            "barcode": null,
            "dimensions": {
                "length": 100,
                "width": 90,
                "height": 80,
                "weight": 200,
                "dimension_unit": null,
                "weight_unit": null
            }
        }
    ],
    "dimensions": null,
    "contains_alcohol": false,
    "contactless_requested": false,
    "tsa_certified_driver_requested": false,
    "signature_requested": false,
    "barcode_scan_requested_at_pickup": false,
    "barcode_scan_requested_at_dropoff": false,
    "require_dropoff_photo": false,
    "additional_services": null,
    "vehicle": null,
    "latest_delivery": null,
    "route": null
}

Important:

• The order id is available immediately — store it and move straight to Step 2: Create Route.
• This endpoint does not accept batch_settings, so routes are never created automatically.

Option 2: Create Orders in Batch (Asynchronous)

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

This endpoint accepts 1-300 orders and queues them for processing. It responds right away with a batch_id; the orders themselves are created in the background, and the resulting order IDs arrive through the webhook configured on your account.

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,
            "unit_price": 100,
            "length": 100,
            "width": 90,
            "height": 80,
            "weight": 200
          }
        ]
      },
      {
        "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

Getting Order IDs and Route IDs

Batch order creation is asynchronous, so the order IDs (and route IDs, if auto_route is enabled) are delivered through the webhook subscription configured on your Burq account. There is no webhook_url field on the request — Burq sends the events to the webhook endpoint registered for your account, so make sure one is configured and subscribed to the batch.* events before submitting a batch.

Batch Webhook Events

Example batch.order_creation_complete Payload

{
  "object": "event",
  "type": "batch.order_creation_complete",
  "data": {
    "batch_id": "batch_abc123",
    "object": "batch_status",
    "status": "completed",
    "metrics": {
      "submitted": 2,
      "created": 2,
      "failed": 0
    },
    "order_ids": ["ord_abc123", "ord_def456"]
  }
}

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

1. Use external_order_ref - Track orders in your system with your own reference
2. Same pickup address - Ensure all orders in a batch share the same pickup address
3. Configure webhooks - Use webhook_url to receive order IDs automatically when batch processing completes
4. Use auto_route - Enable auto_route: true to automatically create routes and skip manual route creation
5. Set routing constraints - Configure max_order_value, max_number_of_orders_per_route, max_route_duration, and max_delivery_radius to control route grouping
6. Accurate item sizes - Correct sizes help with pricing and provider matching
7. Set pickup/dropoff times - Provide realistic timing for better route optimization
8. Batch size - Create batches of reasonable size (e.g., 10-100 orders) for better processing efficiency
9. Save order IDs - Store order IDs from webhook notifications (needed if not using auto_route)
10. 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 (default option if missing):

• 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:

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

Related Documentation

• Authentication - Learn how to authenticate API requests
• Error Handling - Error codes and handling
• Create and dispatch orders with a single API call

← Back to Main Documentation | Next: Create Route →